home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 1 / PC Actual CD 01.iso / share / dos / progr / micro_c.arj / LIBRARY.DOC < prev    next >
Encoding:
Text File  |  1993-10-05  |  175.8 KB  |  6,406 lines

  1.           
  2.           
  3.           
  4.           
  5.           
  6.           
  7.           
  8.           
  9.           
  10.           ===========================================================
  11.                 DDDDD           DDDDD               SSSS
  12.                  D   Dunfield    D   D             S
  13.                  D   D           D   Development    SSSS 
  14.                  D   D           D   D                  Systems
  15.                 DDDDD           DDDDD               SSSS
  16.           ===========================================================
  17.           MM   MM  IIIIIII    CCCC   RRRRRR     OOO             CCCC
  18.           M M M M     I      C    C  R     R   O   O           C    C
  19.           M  M  M     I     C        R     R  O     O         C
  20.           M     M     I     C        RRRRRR   O     O  -----  C
  21.           M     M     I     C        R   R    O     O         C
  22.           M     M     I      C    C  R    R    O   O           C    C
  23.           M     M  IIIIIII    CCCC   R     R    OOO             CCCC
  24.           ===========================================================
  25.     
  26.     
  27.     
  28.     
  29.     
  30.                              A compact 'C' compiler
  31.                                       for
  32.                                  Small Systems.
  33.     
  34.     
  35.                                Library Reference
  36.     
  37.     
  38.     
  39.     
  40.     
  41.                                   Release 3.01
  42.     
  43.                                Revised 27-Aug-93
  44.     
  45.     
  46.     
  47.     
  48.     
  49.     
  50.     
  51.     
  52.     
  53.     
  54.     
  55.     
  56.                        Copyright 1988-1993 Dave Dunfield
  57.                               All rights reserved
  58.     MICRO-C Library                                                  Page: 1
  59.  
  60.  
  61.     1. THE MICRO-C LIBRARIES
  62.     
  63.           The MICRO-C distribution disk includes the 'C'  and  'ASM'  source
  64.        code for a very complete function library which is configured for use
  65.        on an IBM/PC under the MS-DOS operating system. These routines may be
  66.        also be used as "example" programs, providing  insight  into  MICRO-C
  67.        programming techniques.
  68.     
  69.           All functions except for the lowest level I/O routines  are  coded
  70.        in 'C', and should compile on any MICRO-C system. Note that some  low
  71.        level functions in the library are written in 'C' using  still  lower
  72.        level routines. Although this makes the library highly  portable  and
  73.        reduces the number of routines you have to re-write  for  a  specific
  74.        system, the resultant function will be less efficent than  one  which
  75.        directly uses the operating system services.
  76.     
  77.           If you are implementing MICRO-C an a small system  and  intend  to
  78.        use it for serious programming, I strongly recommend that you re-code
  79.        all of the low level library functions in assembly language.
  80.     
  81.           Note that since library routines are often  used  in  applications
  82.        where code size and execution speed are of primary importance, it may
  83.        be desirable to recode some or all of the other library  routines  in
  84.        assembly language as well.
  85.     
  86.           For those who intend to make only casual use of  MICRO-C,  or  who
  87.        wish to experiment with it simply for the  learning  experience,  the
  88.        'C' versions of the low level library functions should be  more  than
  89.        sufficient.
  90.     
  91.           NOTE: If you purchased MICRO-C as  part  of  a  "developers  kit",
  92.        refer to the documentation included with the CPU  support  files  for
  93.        details on the pre-configured library for that CPU, and the functions
  94.        available therein.
  95.     MICRO-C Library                                                  Page: 2
  96.  
  97.  
  98.     
  99.                          +----------------------------+
  100.                          |                            |
  101.                          |  ************************  |
  102.                          |  * The STANDARD library *  |
  103.                          |  ************************  |
  104.                          |                            |
  105.                          +----------------------------+
  106.     
  107.     
  108.     
  109.     
  110.     
  111.     
  112.     
  113.     
  114.     
  115.     
  116.        1.1 STANDARD Library
  117.     
  118.              The library functions described  on  the  following  pages  are
  119.           currently available in the IBM/PC MICRO-C  library  as  "standard"
  120.           functions which are of a general nature, and should be portable to
  121.           most implementations of MICRO-C.
  122.     
  123.              The exact syntax and capabilities of the  system  or  processor
  124.           dependant functions may vary  in  different  implementations,  see
  125.           your  implementation  notes  (READ.ME)  for   details.   Different
  126.           possible forms of such functions are shown using (1), (2), ...  In
  127.           these cases, the form (1) of the function is the one used  in  the
  128.           MS-DOS library.
  129.     ABORT                                                             ABORT
  130.     
  131.     
  132.     
  133.     PROTOTYPE:
  134.     
  135.         abort(char *message)
  136.     
  137.     
  138.     ARGUMENTS:
  139.     
  140.         message - Pointer to message to display
  141.     
  142.     
  143.     RETURN VALUE:
  144.     
  145.         N/A - Function never returns
  146.     
  147.     
  148.     DESCRIPTION:
  149.     
  150.           This function writes the string passed as an argument to  standard
  151.        error, and then terminates the program with a  return  code  of  '-1'
  152.        (Indicating general  failure).  This  provides  a  simple  method  of
  153.        terminating a program on an error condition with a message explaining
  154.        why.
  155.     
  156.     
  157.     EXAMPLES:
  158.     
  159.         abort("Invalid operand\n");
  160.     ABS                                                                 ABS
  161.     
  162.     
  163.     
  164.     PROTOTYPE:
  165.     
  166.         int abs(int number)
  167.     
  168.     
  169.     ARGUMENTS:
  170.     
  171.         number  - Any integer value
  172.     
  173.     
  174.     RETURN VALUE:
  175.     
  176.         The absolute value of "number"
  177.     
  178.     
  179.     DESCRIPTION:
  180.     
  181.           The "abs" function returns the absolute value of the argument.  If
  182.        "number" is a positive value, it is returned unchanged. If  negative,
  183.        the negate of that value is returned (giving a positive result).
  184.     
  185.     
  186.     EXAMPLES:
  187.     
  188.         difference = abs(value1 - value2);
  189.     ATOI                                                               ATOI
  190.     
  191.     
  192.     
  193.     PROTOTYPE:
  194.     
  195.         int atoi(char *string)
  196.     
  197.     
  198.     ARGUMENTS:
  199.     
  200.         string  - Pointer to a string containing a decimal number
  201.     
  202.     
  203.     RETURN VALUE:
  204.     
  205.         16 bit integer value
  206.     
  207.     
  208.     DESCRIPTION:
  209.     
  210.           The "atoi" function converts an ASCII string containing  a  signed
  211.        decimal number (-32768 to 32767) to a 16 bit value which is returned.
  212.        An unsigned number of the range (0 to 65535) may also  be  used,  and
  213.        the result if assigned to an "unsigned" variable will be correct.
  214.     
  215.     
  216.     EXAMPLES:
  217.     
  218.         value = atoi("1234");
  219.         value = atoi("-1");
  220.     CD                                                                   CD
  221.     
  222.     
  223.     
  224.     PROTOTYPE:
  225.     
  226.         int cd(char *pathname)
  227.     
  228.     
  229.     ARGUMENTS:
  230.     
  231.         pathname- Name of directory to make current
  232.     
  233.     
  234.     RETURN VALUE:
  235.     
  236.         0 if successful, otherwise an operating system error code
  237.     
  238.     
  239.     DESCRIPTION:
  240.     
  241.           This function sets the "current" directory, causing all subsequent
  242.        file references which do not explicitly indicate a directory path  to
  243.        access the path specified by "pathname".
  244.     
  245.     
  246.     EXAMPLES:
  247.     
  248.         cd("/mc/c_source");     /* UNIX */
  249.         cd("\\mc\\l_source");   /* MS-DOS */
  250.     CLOSE                                                             CLOSE
  251.     
  252.     
  253.     
  254.     PROTOTYPE:
  255.     
  256.         close(HANDLE fh);
  257.     
  258.     
  259.     ARGUMENTS:
  260.     
  261.         fh      - File handle of an open file
  262.     
  263.     
  264.     RETURN VALUE:
  265.     
  266.         None
  267.     
  268.     
  269.     DESCRIPTION:
  270.     
  271.           This function closes a file  which  was  previously  opened  using
  272.        "open".
  273.     
  274.     
  275.     EXAMPLES:
  276.     
  277.         close(fh);
  278.     CONCAT                                                           CONCAT
  279.     
  280.     
  281.     
  282.     PROTOTYPE:
  283.     
  284.         register concat(char *dest, char *source, ...)
  285.     
  286.     
  287.     ARGUMENTS:
  288.     
  289.         dest    - Pointer to destination string
  290.         source  - Pointer to source string
  291.         ...     - Additional sources may be given
  292.     
  293.     
  294.     RETURN VALUE:
  295.     
  296.         None
  297.     
  298.     
  299.     DESCRIPTION:
  300.     
  301.           The "concat" function concatinates the given source  strings  into
  302.        one destination string. The destination string must be  large  enough
  303.        to hold all of the source strings plus the string  terminator  (zero)
  304.        byte. No value is returned.
  305.     
  306.           NOTE: This function uses a variable number of arguments, and  must
  307.        be declared as "register" (See "stdio.h").
  308.     
  309.     
  310.     EXAMPLES:
  311.     
  312.         concat(filename,"/tmp/", input_name);
  313.     CREATE                                                           CREATE
  314.     
  315.     
  316.     
  317.     PROTOTYPE:
  318.     
  319.         int create(char *pathname, int attrs)
  320.     
  321.     
  322.     
  323.     ARGUMENTS:
  324.     
  325.         pathname- Name of file to create
  326.         attrs   - Attributes for new file
  327.     
  328.     
  329.     RETURN VALUE:
  330.     
  331.         0 if successful, otherwise an operating system error code
  332.     
  333.     
  334.     DESCRIPTION:
  335.     
  336.           The "create" function creates a new file with the specified system
  337.        attributes.
  338.     
  339.           The meaning of the individual bits in the "attrs" value is  system
  340.        dependant, and is defined in the "file.h" header file.
  341.     
  342.     
  343.     EXAMPLES:
  344.     
  345.         create("temp", HIDDEN);
  346.     DELETE                                                           DELETE
  347.     
  348.     
  349.     
  350.     PROTOTYPE:
  351.     
  352.         int delete(char *pathname)
  353.     
  354.     
  355.     
  356.     ARGUMENTS:
  357.     
  358.         pathname- Name of file to delete
  359.     
  360.     
  361.     RETURN VALUE:
  362.     
  363.         0 if successful, otherwise an operating system error code
  364.     
  365.     
  366.     DESCRIPTION:
  367.     
  368.           The "delete" function removes an existing file from the disk.  Any
  369.        disk space occupied by the file is released.
  370.     
  371.     
  372.     EXAMPLES:
  373.     
  374.         delete("temp");
  375.     EXIT                                                               EXIT
  376.     
  377.     
  378.     
  379.     PROTOTYPE:
  380.     
  381.         exit(int rc)
  382.     
  383.     
  384.     ARGUMENTS:
  385.     
  386.         rc      - Termination return code
  387.     
  388.     
  389.     RETURN VALUE:
  390.     
  391.         N/A - Function never returns
  392.     
  393.     
  394.     DESCRIPTION:
  395.     
  396.           This function terminates the execution of the program and passes a
  397.        specific return code back to the  operating  system.  A  return  code
  398.        value of zero is used  to  indicate  successful  program  completion.
  399.        Non-zero return code values may be used to indicate a particular type
  400.        of failure. A value of '-1' is often used to indicate a  non-specific
  401.        failure. Note that  the  "rc"  value  is  very  system  specific,  in
  402.        particular, some systems support only 8 bit return codes,  so  values
  403.        which are greater than 255 should be avoided.
  404.     
  405.     
  406.     EXAMPLES:
  407.     
  408.         exit(0);        /* success */
  409.         exit(-1);       /* failure */
  410.     FCLOSE                                                           FCLOSE
  411.     
  412.     
  413.     
  414.     PROTOTYPE:
  415.     
  416.         fclose(FILE *fp);
  417.     
  418.     
  419.     ARGUMENTS:
  420.     
  421.         fp      - File pointer to an open file
  422.     
  423.     
  424.     RETURN VALUE:
  425.     
  426.         None
  427.     
  428.     
  429.     DESCRIPTION:
  430.     
  431.           This function closes a file  which  was  previously  opened  using
  432.        "fopen". The I/O buffer space used by the file is  released.  In  the
  433.        case of a file open for write ('w'), the last disk buffer is  flushed
  434.        and written to disk.
  435.     
  436.     
  437.     EXAMPLES:
  438.     
  439.         fclose(fp);
  440.     FFLUSH                                                           FFLUSH
  441.     
  442.     
  443.     
  444.     PROTOTYPE:
  445.     
  446.         fflush(FILE *fp)
  447.     
  448.     
  449.     ARGUMENTS:
  450.     
  451.         fp       File pointer to an open file
  452.     
  453.     
  454.     RETURN VALUE:
  455.     
  456.         0 if successful, otherwise an operating system error code
  457.     
  458.     
  459.     DESCRIPTION:
  460.     
  461.           The "fflush" function flushes the I/O buffers for the  given  open
  462.        file. If the file is opened for WRITE, this causes any data remaining
  463.        in a partially filled output buffer to be written.  If  the  file  is
  464.        opened for READ, this has the effect of throwing away any data  which
  465.        is pending in the input buffer.
  466.     
  467.     
  468.     EXAMPLES:
  469.     
  470.         fputs("Enter you name?", stdout);
  471.         fflush(stdout);         /* Make sure prompt is output */
  472.         fgets(name, 80, stdin);
  473.     FGETS                                                             FGETS
  474.     
  475.     
  476.     
  477.     PROTOTYPE:
  478.     
  479.         char *fgets(char *buffer, int size, FILE *fp)
  480.     
  481.     
  482.     ARGUMENTS:
  483.     
  484.         buffer  - Pointer to string to receive line
  485.         size    - Maximum size of line to read
  486.         fp      - File pointer to an input file
  487.     
  488.     
  489.     RETURN VALUE:
  490.     
  491.         Pointer to "buffer", or 0 if end of file
  492.     
  493.     
  494.     DESCRIPTION:
  495.     
  496.           The "fgets" function reads characters  from  the  specified  input
  497.        file, and places them in the character  buffer  until  one  of  three
  498.        things happens:
  499.     
  500.           1) A NEWLINE character is encountered.
  501.     
  502.           2) The END of the file is encountered.
  503.     
  504.           3) The limit of "size" character is read.
  505.     
  506.           The string is terminated with the standard  NULL  (00)  character.
  507.        The trailing NEWLINE '\n' character is NOT  included  in  the  output
  508.        buffer.
  509.     
  510.     
  511.     EXAMPLES:
  512.     
  513.         fgets(input_line, 80, input_file);
  514.     FIND_FIRST                                                   FIND_FIRST
  515.     
  516.     
  517.     
  518.     PROTOTYPE:
  519.     
  520.         int find_first(char *pattern, int mattrs, char name[], int &sizeh,
  521.                        int &sizel, int &attrs, int &time, int &date)
  522.     
  523.     
  524.     ARGUMENTS:
  525.     
  526.         pattern - File name pattern to match
  527.         mattrs  - File attributes to match
  528.         name    - Address of string to receive file name
  529.         &sizeh  - Address of int to receive high word of size
  530.         &sizel  - Address of int to receive low word of size
  531.         &attrs  - Address of int to receive attributes
  532.         &time   - Address of int to receive time stamp
  533.         &date   - Address of int to receive date stamp
  534.     
  535.     
  536.     RETURN VALUE:
  537.     
  538.         0 if successful, otherwise an operating system error code
  539.     
  540.     
  541.     DESCRIPTION:
  542.     
  543.           This function locates the first file on the disk which matches the
  544.        given pattern. The "mattrs" field specifies  any  special  attributes
  545.        the files must have  in  order  to  be  matched,  use  0  for  normal
  546.        directory searches.
  547.     
  548.           Subsequent files may be located using the "find_next" function.
  549.     
  550.           The above function prototype describes the  MS-DOS  implementation
  551.        of the function. With other operating systems, the function may  have
  552.        slightly  different  parameters,   due   to   differing   information
  553.        available. See your implementation notes.
  554.     
  555.     
  556.     EXAMPLES:
  557.     
  558.         if(find_first(pattern, 0, name, &sh, &sl, &a, &t, &d))
  559.             abort("No matching files found\n");
  560.     FIND_NEXT                                                     FIND_NEXT
  561.     
  562.     
  563.     
  564.     PROTOTYPE:
  565.     
  566.         int find_next(char name[], int &sizeh, int &sizel, int &attrs,
  567.                       int &time, int &date)
  568.     
  569.     
  570.     ARGUMENTS:
  571.     
  572.         name    - Address of string to receive file name
  573.         &sizeh  - Address of int to receive high word of size
  574.         &sizel  - Address of int to receive low word of size
  575.         &attrs  - Address of int to receive attributes
  576.         &time   - Address of int to receive time stamp
  577.         &date   - Address of int to receive date stamp
  578.     
  579.     
  580.     RETURN VALUE:
  581.     
  582.         0 if successful, otherwise an operating system error code
  583.     
  584.     
  585.     DESCRIPTION:
  586.     
  587.           The function must be preceeded by a call to "find_first", and will
  588.        locate the next file on  the  disk  which  matches  the  pattern  and
  589.        attributes given to that function call.
  590.     
  591.           The above function prototype describes the  MS-DOS  implementation
  592.        of the function. With other operating systems, the function may  have
  593.        slightly  different  parameters,   due   to   differing   information
  594.        available. See your implementation notes.
  595.     
  596.     
  597.     EXAMPLES:
  598.     
  599.         do
  600.             printf("%s\n", name);
  601.         while(!find_next(name, &sh, &sl, &a, &t, &d));
  602.     FOPEN                                                             FOPEN
  603.     
  604.     
  605.     
  606.     PROTOTYPE:
  607.     
  608.         FILE *fopen(char *filename, char *options)
  609.     
  610.     
  611.     ARGUMENTS:
  612.     
  613.         filename- Name of the file to open
  614.         options - String containing open options:
  615.                     'a' - Append to file (must use with 'w')
  616.                     'b' - Binary mode (default is text)
  617.                     'q' - Quit { exit(-1) } on failure
  618.                     'r' - Open file for read
  619.                     'v' - Issue error message on failure
  620.                     'w' - Open file for write
  621.     
  622.     
  623.     RETURN VALUE:
  624.     
  625.         File pointer to the file buffer for the open file
  626.         Zero (0) if file could not be opened
  627.     
  628.     
  629.     DESCRIPTION:
  630.     
  631.           This function opens a file for  buffered  input  ('r')  or  output
  632.        ('w'), allowing subsequent I/O operations to read or write the  file.
  633.        If the 'b' option is NOT included, the file is assumed to be  a  TEXT
  634.        file, and appropriate translations  are  made  for  NEWLINE  and  EOF
  635.        interpretation.
  636.     
  637.           The size of the I/O buffer used is established by "fopen" from the
  638.        external variable 'IOB_size',  which  has  a  default  value  of  256
  639.        (bytes). This variable is defined in the 'file.h'  header  file,  and
  640.        may be modified prior to calling this function if you wish to  use  a
  641.        different buffer size.
  642.     
  643.           One I/O buffer is allocated from the heap for each open file. When
  644.        using a large IOB_size value, you must be careful not to consume more
  645.        memory than is available.
  646.     
  647.     
  648.     EXAMPLES:
  649.     
  650.         fp = fopen("input_file", "r");
  651.         fp = fopen("input_file", "rvq");
  652.         IOB_size = 1024*10;         /* Set up a 10K buffer */
  653.         fp = fopen("output_file", "wb");
  654.     FPRINTF                                                         FPRINTF
  655.     
  656.     
  657.     
  658.     PROTOTYPE:
  659.     
  660.         register fprintf(FILE *fp, char *format, arg, ...)
  661.     
  662.     
  663.     ARGUMENTS:
  664.     
  665.         fp      - File pointer to an output file
  666.         format  - Pointer to format string
  667.         arg     - Argument as determined by format string
  668.         ...     - Additional arguments may be required
  669.     
  670.     
  671.     RETURN VALUE:
  672.     
  673.         None
  674.     
  675.     
  676.     DESCRIPTION:
  677.     
  678.           This routine performs a formatted print to  a  file  specified  by
  679.        'fp'. The 'format' string is written to the file with  the  arguments
  680.        substituted for special "conversion  characters".  These  "conversion
  681.        characters" are identified by a preceeding '%', and may be one of the
  682.        following:
  683.     
  684.                     b       - Binary number
  685.                     c       - Character
  686.                     d       - Decimal (signed) number
  687.                     o       - Octal number
  688.                     s       - String
  689.                     u       - Unsigned decimal number
  690.                     x       - Hexidecimal number
  691.                     %       - A single percent sign (No argument used)
  692.     
  693.           A numeric "field width" specifier may be placed in between the '%'
  694.        and the conversion character, in which case the value will be  output
  695.        in a field of that width. If the "field width" is a negative  number,
  696.        the output will be left justified in the field, otherwise it is right
  697.        justified. If the field width contains a leading '0', then the output
  698.        field will be padded with zero's, otherwise spaces are used.
  699.     
  700.           If no "field width" is given, the output  is  free  format,  using
  701.        only as much space as required.
  702.     
  703.           NOTE: This function uses a variable number of arguments, and  must
  704.        be declared as "register" (See "stdio.h").
  705.     
  706.     
  707.     EXAMPLES:
  708.     
  709.         fprintf(stderr,"Filename='%s'\n", filename);
  710.         fprintf(stdout,"Address=%04x\n", address);
  711.         fprintf(outfile,"Amount: $%3u.%02u\n", amount / 100, amount % 100);
  712.     FPUTS                                                             FPUTS
  713.     
  714.     
  715.     
  716.     PROTOTYPE:
  717.     
  718.         fputs(char *string, FILE *fp)
  719.     
  720.     
  721.     ARGUMENTS:
  722.     
  723.         string  - Pointer to a character string
  724.         fp      - FIle pointer to output file
  725.     
  726.     
  727.     RETURN VALUE:
  728.     
  729.         0 if successful, otherwise an operating system error code
  730.     
  731.     
  732.     DESCRIPTION:
  733.     
  734.           The "fputs" function writes the specified string to the  indicated
  735.        output file. The zero terminating the string is NOT written.
  736.     
  737.     
  738.     EXAMPLES:
  739.     
  740.         fputs("Text message", output_file);
  741.     FREAD                                                             FREAD
  742.     
  743.     
  744.     
  745.     PROTOTYPE:
  746.     
  747.         int fread(char *buffer, int size, FILE *fp)
  748.     
  749.     
  750.     ARGUMENTS:
  751.     
  752.         buffer  - Pointer to buffer to receive data
  753.         size    - Number of bytes to read
  754.         fp      - File pointer to an input file
  755.     
  756.     
  757.     RETURN VALUE:
  758.     
  759.         Number of bytes read from file
  760.     
  761.     
  762.     DESCRIPTION:
  763.     
  764.           This function reads a block of data from a file and places  it  in
  765.        memory at the address of "buffer". Data will be read in  either  TEXT
  766.        or BINARY form, depending on how the file was opened. If  the  number
  767.        of bytes returned is less than the number of bytes requested,  either
  768.        the end of the file was encountered or an error condition occured (in
  769.        which case the value will be zero).
  770.     
  771.     
  772.     EXAMPLES:
  773.     
  774.         fread(block, 512, input_fp);
  775.     FREE                                                               FREE
  776.     
  777.     
  778.     
  779.     PROTOTYPE:
  780.     
  781.         free(char *ptr)
  782.     
  783.     
  784.     ARGUMENTS:
  785.     
  786.         ptr     - Pointer to a previously allocated memory block
  787.     
  788.     
  789.     RETURN VALUE:
  790.     
  791.         None
  792.     
  793.     
  794.     DESCRIPTION:
  795.     
  796.           The "free" function releases (de-allocates) a block of memory that
  797.        was obtained via a call to "malloc", and returns it to the heap. This
  798.        makes it available for use by other memory allocations.
  799.     
  800.     
  801.     EXAMPLES:
  802.     
  803.         if(!(ptr = malloc(BUFSIZ)))     /* Allocate a temporary buffer */
  804.             abort("Not enough memory");
  805.         do {                            /* Copy the file over */
  806.             size = fread(ptr, BUFSIZ, in_fp);
  807.             fwrite(ptr, size, out_fp); }
  808.         while(size == BUFSIZ);
  809.         free(ptr);                      /* Release temporary buffer */
  810.     FSCANF                                                           FSCANF
  811.     
  812.     
  813.     
  814.     PROTOTYPE:
  815.     
  816.         register int fscanf(FILE *fp, char *format, &arg, ...)
  817.     
  818.     
  819.     ARGUMENTS:
  820.     
  821.         fp      - File pointer to an input file
  822.         format  - Pointer to format string
  823.         arg     - Argument as determined by format string
  824.         ...     - Additional arguments may be required
  825.     
  826.     
  827.     RETURN VALUE:
  828.     
  829.         The number of successful matches
  830.         EOF (-1) if end of file or an error condition occurs
  831.     
  832.     
  833.     DESCRIPTION:
  834.     
  835.           This routine reads a line from the specified file and scans it for
  836.        specific values which  are  then  assigned  to  the  passed  argument
  837.        addresses. The types of values  scanned  are  determined  by  special
  838.        "conversion characters" within the "format" string. These "conversion
  839.        characters" are identified by a preceeding '%', and may be one of the
  840.        following:
  841.     
  842.                     b       - Binary number
  843.                     c       - Character
  844.                     d       - Decimal (signed) number
  845.                     o       - Octal number
  846.                     s       - String
  847.                     u       - Unsigned decimal number
  848.                     x       - Hexidecimal number
  849.                     %       - A single percent sign (No argument used)
  850.     
  851.           Before scanning for any value other than '%c', any leading "space"
  852.        or "tab" characters in the input line are automatically flushed.
  853.     
  854.           Scanning of a particular value type will terminate when either the
  855.        end of  the  line  or  a  non-applicible  character  is  encountered.
  856.        Scanning of strings (%s) stops with a "space" or "tab" character, and
  857.        the stored string will be zero terminated.
  858.     
  859.           A numeric "field width" specifier may be placed in between the '%'
  860.        and the conversion character, in which case  scanning  of  the  value
  861.        will  also  terminate  if  that  many  input  characters  have   been
  862.        processed.
  863.     
  864.           Scanning  for  characters  (%c)  assumes  a  "field  width"  of  1
  865.        character unless otherwise specified. If a field width is  specified,
  866.        the output is assumed to be  a  string,  and  a  zero  terminator  is
  867.        appended.
  868.     
  869.     
  870.     
  871.     
  872.     
  873.     
  874.     
  875.     
  876.     
  877.     
  878.           Any other (non-conversion) characters in the  format  string  will
  879.        cause the next character in the input string which is not  a  "space"
  880.        or "tab" to be skipped if it matches that character.
  881.     
  882.           Any variable values from the input line  which  are  not  required
  883.        must be cleared by scanning them into a "dummy" variable.
  884.     
  885.           The most common mistake when using "fscanf" is forgetting  to  use
  886.        the '&'  operator  with  a  simple  variable  argument.  This  causes
  887.        "fscanf" to store the value INDIRECTLY at the  address  contained  in
  888.        that variable (Similar to  using  '*'  with  a  pointer)  instead  of
  889.        storing the value into the actual variable  itself.  Arguments  which
  890.        are array names do not require the '&' operator, since the address of
  891.        the array is already generated by reference to its name.
  892.     
  893.           Unlike "fscanf" in most  other  compiler  libraries,  the  MICRO-C
  894.        function always reads and scans a single line from the input file.
  895.     
  896.           NOTE: This function uses a variable number of arguments, and  must
  897.        be declared as "register".
  898.     
  899.     
  900.     EXAMPLES:
  901.     
  902.         if(fscanf(infile,"%s %s %u", first_name, last_name, &age) != 3)
  903.             abort("Error in user record\n");
  904.     FSEEK                                                             FSEEK
  905.     
  906.     
  907.     
  908.     PROTOTYPE:
  909.     
  910.         (1) int fseek(FILE *fp, int h_offset, unsigned l_offset, int mode)
  911.         (2) int fseek(FILE *fp, int offset, mode)
  912.     
  913.     
  914.     ARGUMENTS:
  915.     
  916.         fp      - File pointer to an open file
  917.         h_offset- Highest 16 bits of offset value
  918.         l_offset- Lowest 16 bits of offset value
  919.         offset  - 16 bit offset value
  920.         mode    - Type of seek
  921.                     0 = Absolute from start of file
  922.                     1 = Signed offset from current position
  923.                     2 = Signed offset from end of file
  924.     
  925.     
  926.     RETURN VALUE:
  927.     
  928.         0 if successful, otherwise an operating system error code
  929.     
  930.     
  931.     DESCRIPTION:
  932.     
  933.           This function positions the operating system internal pointer into
  934.        a file so that any read or write will take  place  at  the  specified
  935.        position in the file.
  936.     
  937.           Most operating systems which support files of > 64K bytes in  size
  938.        will support form (1) of the function, using both high and low offset
  939.        values.
  940.     
  941.           Smaller operating  systems  may  only  support  form  (2)  of  the
  942.        function, allowing seeking of only +/- 32K bytes.
  943.     
  944.           Also, some implementations may not support  all  "modes",  or  may
  945.        only allow unsigned (positive) offsets.
  946.     
  947.     
  948.     EXAMPLES:
  949.     
  950.         fseek(in_file, 0, 2);   /* Advance to end of file */
  951.     FTELL                                                             FTELL
  952.     
  953.     
  954.     
  955.     PROTOTYPE:
  956.     
  957.         (1) int ftell(FILE *fp, int &h_offset, unsigned &l_offset)
  958.         (2) int ftell(FILE *fp, int &offset)
  959.     
  960.     
  961.     ARGUMENTS:
  962.     
  963.         fp      - File pointer to an open file
  964.         h_offset- Address of int to receive high word of offset
  965.         l_offset- Address of int to receive low word of offset
  966.         offset  - Address of int to receive offset
  967.     
  968.     
  969.     RETURN VALUE:
  970.     
  971.         0 if successful, otherwise an operating system error code
  972.     
  973.     
  974.     DESCRIPTION:
  975.     
  976.           This function gets the current read/write position within a  file.
  977.        The position returned indicates the absolute character (byte)  offset
  978.        from the start of the file where the next read  or  write  will  take
  979.        place.
  980.     
  981.           Most operating systems which support files of > 64K bytes in  size
  982.        will support form (1) of the function, returning both  high  and  low
  983.        offset values.
  984.     
  985.           Smaller operating  systems  may  only  support  form  (2)  of  the
  986.        function,  allowing  access  to  only  the  first   65535   character
  987.        positions.
  988.     
  989.     
  990.     EXAMPLES:
  991.     
  992.         ftell(fp, &oldh, &oldl);    /* Save file position */
  993.             . . .                   /* Perform some operations on the file */
  994.         fseek(fp, oldh, oldl, 0);   /* Return to previous position */
  995.     FWRITE                                                           FWRITE
  996.     
  997.     
  998.     
  999.     PROTOTYPE:
  1000.     
  1001.         int fwrite(char *block, int size, FILE *fp)
  1002.     
  1003.     
  1004.     ARGUMENTS:
  1005.     
  1006.         block   - Pointer to a block of data to write
  1007.         size    - Number of bytes to write
  1008.         fp      - File pointer to an output file
  1009.     
  1010.     
  1011.     RETURN VALUE:
  1012.     
  1013.         The number of bytes written to the file
  1014.     
  1015.     
  1016.     DESCRIPTION:
  1017.     
  1018.           This function writes a block of data to the  indicated  file  from
  1019.        memory at the specified address. Data is written in  either  TEXT  or
  1020.        BINARY mode, depending on how the  file  was  opened.  If  the  value
  1021.        returned is less than the value of the "size" parameter,  some  error
  1022.        condition has occured (Such as disk full).
  1023.     
  1024.     
  1025.     EXAMPLES:
  1026.     
  1027.         if(fwrite(buffer, 100, fp) < 100)
  1028.             abort("File write error\n");
  1029.     GETC                                                               GETC
  1030.     
  1031.     
  1032.     
  1033.     PROTOTYPE:
  1034.     
  1035.         int getc(FILE *fp)
  1036.     
  1037.     
  1038.     ARGUMENTS:
  1039.     
  1040.         fp      - File pointer to an input file
  1041.     
  1042.     
  1043.     RETURN VALUE:
  1044.     
  1045.         Value of a character read from the file (0-255)
  1046.         EOF (-1) if end of file or an error condition occurs
  1047.     
  1048.     
  1049.     DESCRIPTION:
  1050.     
  1051.           This function reads a single character from  an  input  file,  and
  1052.        returns it as a positive value in the range of 0 to 255.  A  full  16
  1053.        bit value is returned, allowing the  end  of  file  condition  to  be
  1054.        distinct from the character value 255.
  1055.     
  1056.     
  1057.     EXAMPLES:
  1058.     
  1059.         if((c = getc(input_file)) == EOF)
  1060.             abort("End of file encountered\n");
  1061.     GETDIR                                                           GETDIR
  1062.     
  1063.     
  1064.     
  1065.     PROTOTYPE:
  1066.     
  1067.         int getdir(char pathname[])
  1068.     
  1069.     
  1070.     ARGUMENTS:
  1071.     
  1072.         pathname- Address of string to receive directory path
  1073.     
  1074.     
  1075.     RETURN VALUE:
  1076.     
  1077.         0 if successful, otherwise an operating system error code
  1078.     
  1079.     
  1080.     DESCRIPTION:
  1081.     
  1082.           This function retreives from the system the name of the  "current"
  1083.        directory path.
  1084.     
  1085.           The "pathname" string must be long  enough  to  hold  the  largest
  1086.        pathname supported by the system, as  indicated  by  the  "PATH_SIZE"
  1087.        definition in the "file.h" header file.
  1088.     
  1089.     
  1090.     EXAMPLES:
  1091.     
  1092.         getdir(¤t_dir);
  1093.     GETENV                                                           GETENV
  1094.     
  1095.     
  1096.     
  1097.     PROTOTYPE:
  1098.     
  1099.         int getenv(char *ename, char *dest)
  1100.     
  1101.     
  1102.     ARGUMENTS:
  1103.     
  1104.         ename   - String containing name of environment variable
  1105.         dest    - Buffer to receive variable string value
  1106.     
  1107.     
  1108.     RETURN VALUE:
  1109.     
  1110.         1 if environment variable was found, 0 if not.
  1111.     
  1112.     
  1113.     DESCRIPTION:
  1114.     
  1115.           The GETENV function gets the value of a variable in  the  programs
  1116.        environment, and returns it as a string. If the environment  variable
  1117.        is not found, zero is returned, and the destination buffer is set  to
  1118.        a null (zero length) string.
  1119.     
  1120.           Use of this  function  allows  a  programs  fixed  parameters  and
  1121.        options to be specified once in environment variables, which may then
  1122.        be extracted by the program, eliminating the need  to  specify  those
  1123.        values every time the program is executed.
  1124.     
  1125.           When operating  MICRO-C  under  operating  systems  which  do  not
  1126.        support environment variables, this function will not be available.
  1127.     
  1128.     
  1129.     EXAMPLES:
  1130.     
  1131.         if(!getenv("COMSPEC", command))
  1132.             abort("No command processor defined\n");
  1133.     IN                                                                   IN
  1134.     
  1135.     
  1136.     
  1137.     PROTOTYPE:
  1138.     
  1139.         int in(unsigned port)
  1140.     
  1141.     
  1142.     ARGUMENTS:
  1143.     
  1144.         port    - I/O port address
  1145.     
  1146.     
  1147.     RETURN VALUE:
  1148.     
  1149.         The 8 bit value read from the given I/O port address
  1150.     
  1151.     
  1152.     DESCRIPTION:
  1153.     
  1154.           The "in" function reads and returns a byte (8 bits)  from  an  I/O
  1155.        port as an integer value between 0 and 255.
  1156.     
  1157.           The valid range of values for "port" depends on  the  I/O  address
  1158.        space of the processor.
  1159.     
  1160.           This function is not provided for processors which do not  support
  1161.        a separate I/O address space.
  1162.     
  1163.     
  1164.     EXAMPLES:
  1165.     
  1166.         while(in(0));   /* Wait for flag to clear */
  1167.     INW                                                                 INW
  1168.     
  1169.     
  1170.     
  1171.     PROTOTYPE:
  1172.     
  1173.         int inw(unsigned port)
  1174.     
  1175.     
  1176.     ARGUMENTS:
  1177.     
  1178.         port    - I/O port address
  1179.     
  1180.     
  1181.     RETURN VALUE:
  1182.     
  1183.         The 16 bit value read from the given I/O port address
  1184.     
  1185.     
  1186.     DESCRIPTION:
  1187.     
  1188.           The "inw" function reads and returns a word (16 bits) from an  I/O
  1189.        port as an integer value between 0 and 65535 (-1).
  1190.     
  1191.           The valid range of values for "port" depends on  the  I/O  address
  1192.        space of the processor.
  1193.     
  1194.           This function is not provided for processors which do not  support
  1195.        a separate I/O address space.
  1196.     
  1197.     
  1198.     EXAMPLES:
  1199.     
  1200.         var = inw(0);
  1201.     ISASCII                                                         ISASCII
  1202.     
  1203.     
  1204.     
  1205.     PROTOTYPE:
  1206.     
  1207.         int isascii(int c)
  1208.     
  1209.     
  1210.     ARGUMENTS:
  1211.     
  1212.         c       - Any character value
  1213.     
  1214.     
  1215.     RETURN VALUE:
  1216.     
  1217.         1 if 'c' is an ASCII character
  1218.         0 if 'c' is not an ASCII character
  1219.     
  1220.     
  1221.     DESCRIPTION:
  1222.     
  1223.           Returns TRUE (1) if the passed character  'c'  is  a  valid  ASCII
  1224.        character (0x00-0xFF), otherwise FALSE (0) is returned.
  1225.     
  1226.     
  1227.     EXAMPLES:
  1228.     
  1229.         if(!isascii(*ptr))
  1230.             abort("Invalid character data");
  1231.     ISALNUM                                                         ISALNUM
  1232.     
  1233.     
  1234.     
  1235.     PROTOTYPE:
  1236.     
  1237.         int isalnum(char c)
  1238.     
  1239.     
  1240.     ARGUMENTS:
  1241.     
  1242.         c       - Any character value
  1243.     
  1244.     
  1245.     RETURN VALUE:
  1246.     
  1247.         1 if 'c' is alphabetic or numeric
  1248.         0 if 'c' is not alphabetic or numeric
  1249.     
  1250.     
  1251.     DESCRIPTION:
  1252.     
  1253.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1254.        alphabetic letter in either upper or  lower  case  or  if  'c'  is  a
  1255.        numeric digit, otherwise FALSE (0) is returned.
  1256.     
  1257.     
  1258.     EXAMPLES:
  1259.     
  1260.         while(isalnum(*ptr))        /* Copy over symbol name */
  1261.             *name++ = *ptr++;
  1262.     ISALPHA                                                         ISALPHA
  1263.     
  1264.     
  1265.     
  1266.     PROTOTYPE:
  1267.     
  1268.         int isalpha(char c)
  1269.     
  1270.     
  1271.     ARGUMENTS:
  1272.     
  1273.         c       - Any character value
  1274.     
  1275.     
  1276.     RETURN VALUE:
  1277.     
  1278.         1 if 'c' is alphabetic
  1279.         0 if 'c' is not alphabetic
  1280.     
  1281.     
  1282.     DESCRIPTION:
  1283.     
  1284.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1285.        alphabetic letter in either upper or lower case, otherwise FALSE  (0)
  1286.        is returned.
  1287.     
  1288.     
  1289.     EXAMPLES:
  1290.     
  1291.         flag = isalpha(input_char);
  1292.     ISCNTRL                                                         ISCNTRL
  1293.     
  1294.     
  1295.     
  1296.     PROTOTYPE:
  1297.     
  1298.         int iscntrl(char c)
  1299.     
  1300.     
  1301.     ARGUMENTS:
  1302.     
  1303.         c       - Any character value
  1304.     
  1305.     
  1306.     RETURN VALUE:
  1307.     
  1308.         1 if 'c' is a "control" character
  1309.         0 if 'c' is not a "control" character
  1310.     
  1311.     
  1312.     DESCRIPTION:
  1313.     
  1314.           Returns TRUE (1) is the passed character 'c' is an ASCII "control"
  1315.        character (0x00-0x1F or 0x7F), otherwise FALSE (0) is returned.
  1316.     
  1317.     
  1318.     EXAMPLES:
  1319.     
  1320.         putc(iscntrl(c) ? '.' : c, stdout); /* Display controls as '.' */
  1321.     ISDIGIT                                                         ISDIGIT
  1322.     
  1323.     
  1324.     
  1325.     PROTOTYPE:
  1326.     
  1327.         int isdigit(char c)
  1328.     
  1329.     
  1330.     ARGUMENTS:
  1331.     
  1332.         c       - Any character value
  1333.     
  1334.     
  1335.     RETURN VALUE:
  1336.     
  1337.         1 if 'c' is numeric
  1338.         0 if 'c' is not numeric
  1339.     
  1340.     
  1341.     DESCRIPTION:
  1342.     
  1343.           Returns TRUE (1) is the passed character 'c'  is  an  ASCII  digit
  1344.        ('0'-'9'), otherwise FALSE (0) is returned.
  1345.     
  1346.     
  1347.     EXAMPLES:
  1348.     
  1349.         value = 0;
  1350.         while(isdigit(*ptr))
  1351.             value = (value * 10) + (*ptr++ - '0');
  1352.     ISGRAPH                                                         ISGRAPH
  1353.     
  1354.     
  1355.     
  1356.     PROTOTYPE:
  1357.     
  1358.         int isgraph(char c)
  1359.     
  1360.     
  1361.     ARGUMENTS:
  1362.     
  1363.         c       - Any character value
  1364.     
  1365.     
  1366.     RETURN VALUE:
  1367.     
  1368.         1 if 'c' is a non-space printable character
  1369.         0 if 'c' is a space or not printable
  1370.     
  1371.     
  1372.     DESCRIPTION:
  1373.     
  1374.           Returns TRUE (1) if the passed character 'c' is a printable  ASCII
  1375.        character other than  a  space  character,  otherwise  FALSE  (0)  is
  1376.        returned.
  1377.     
  1378.     
  1379.     EXAMPLES:
  1380.     
  1381.         putc(isgraph(c) ? c : '.', stdout);
  1382.     ISLOWER                                                         ISLOWER
  1383.     
  1384.     
  1385.     
  1386.     PROTOTYPE:
  1387.     
  1388.         int islower(char c)
  1389.     
  1390.     
  1391.     ARGUMENTS:
  1392.     
  1393.         c       - Any character value
  1394.     
  1395.     
  1396.     RETURN VALUE:
  1397.     
  1398.         1 if 'c' is lower case alphabetic
  1399.         0 if 'c' is not lower case alphabetic
  1400.     
  1401.     
  1402.     DESCRIPTION:
  1403.     
  1404.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1405.        alphabetic letter of lower case, otherwise FALSE (0) is returned.
  1406.     
  1407.     
  1408.     EXAMPLES:
  1409.     
  1410.         flag = islower(input_char);
  1411.     ISPRINT                                                         ISPRINT
  1412.     
  1413.     
  1414.     
  1415.     PROTOTYPE:
  1416.     
  1417.         int isprint(char c)
  1418.     
  1419.     
  1420.     ARGUMENTS:
  1421.     
  1422.         c       - Any character value
  1423.     
  1424.     
  1425.     RETURN VALUE:
  1426.     
  1427.         1 if 'c' is a printable character
  1428.         0 if 'c' is not printable
  1429.     
  1430.     
  1431.     DESCRIPTION:
  1432.     
  1433.           Returns TRUE (1) if the passed character 'c' is a printable  ASCII
  1434.        character (0x20-0xFE), otherwise FALSE (0) is returned.
  1435.     
  1436.     
  1437.     EXAMPLES:
  1438.     
  1439.         putc(isprint(c) ? c : '.', stdout);
  1440.     ISPUNCT                                                         ISPUNCT
  1441.     
  1442.     
  1443.     
  1444.     PROTOTYPE:
  1445.     
  1446.         int ispunct(char c)
  1447.     
  1448.     
  1449.     ARGUMENTS:
  1450.     
  1451.         c       - Any character value
  1452.     
  1453.     
  1454.     RETURN VALUE:
  1455.     
  1456.         1 if 'c' is a printable non-alphanumeric character
  1457.         0 if 'c' is not printable or alphanumeric
  1458.     
  1459.     
  1460.     DESCRIPTION:
  1461.     
  1462.           Returns TRUE (1) if the passed character 'c' is a printable  ASCII
  1463.        character which is not a letter of the alphabet or a  numeric  digit,
  1464.        otherwise FALSE (0) is returned.
  1465.     
  1466.     
  1467.     EXAMPLES:
  1468.     
  1469.         while(ispunct(*ptr))
  1470.             ++ptr;
  1471.     ISSPACE                                                         ISSPACE
  1472.     
  1473.     
  1474.     
  1475.     PROTOTYPE:
  1476.     
  1477.         int isspace(char c)
  1478.     
  1479.     
  1480.     ARGUMENTS:
  1481.     
  1482.         c       - Any character value
  1483.     
  1484.     
  1485.     RETURN VALUE:
  1486.     
  1487.         1 if 'c' is a space character (space, tab or newline)
  1488.         0 if 'c' is not a space character
  1489.     
  1490.     
  1491.     DESCRIPTION:
  1492.     
  1493.           Returns TRUE (1) if the passed character 'c' is one  of  a  space,
  1494.        tab or newline, otherwise FALSE (0) is returned.
  1495.     
  1496.     
  1497.     EXAMPLES:
  1498.     
  1499.         while(isspace(*ptr))
  1500.             ++ptr;
  1501.     ISUPPER                                                         ISUPPER
  1502.     
  1503.     
  1504.     
  1505.     PROTOTYPE:
  1506.     
  1507.         int isupper(char c)
  1508.     
  1509.     
  1510.     ARGUMENTS:
  1511.     
  1512.         c       - Any character value
  1513.     
  1514.     
  1515.     RETURN VALUE:
  1516.     
  1517.         1 if 'c' is upper case alphabetic
  1518.         0 if 'c' is not upper case alphabetic
  1519.     
  1520.     
  1521.     DESCRIPTION:
  1522.     
  1523.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1524.        alphabetic letter of upper case, otherwise FALSE (0) is returned.
  1525.     
  1526.     
  1527.     EXAMPLES:
  1528.     
  1529.         flag = isupper(input_char);
  1530.     ISXDIGIT                                                       ISXDIGIT
  1531.     
  1532.     
  1533.     
  1534.     PROTOTYPE:
  1535.     
  1536.         int isxdigit(char c)
  1537.     
  1538.     
  1539.     ARGUMENTS:
  1540.     
  1541.         c       - Any character value
  1542.     
  1543.     
  1544.     RETURN VALUE:
  1545.     
  1546.         1 if 'c' is a hexidecimal digit
  1547.         0 if 'c' is not a hexidecimal digit
  1548.     
  1549.     
  1550.     DESCRIPTION:
  1551.     
  1552.           Returns TRUE (1) is the passed character 'c'  is  an  valid  ASCII
  1553.        hexidecimal digit ('0'-'9', 'A'-'F', 'a'-'f'), otherwise FALSE (0) is
  1554.        returned.
  1555.     
  1556.     
  1557.     EXAMPLES:
  1558.     
  1559.         value = 0;
  1560.         while(isxdigit(*ptr))
  1561.             value = (value * 16) +
  1562.                 (isdigit(*ptr) ? *ptr++ - '0' : toupper(*ptr++) - ('A'-10));
  1563.     LGETC                                                             LGETC
  1564.     
  1565.     
  1566.     
  1567.     PROTOTYPE:
  1568.     
  1569.         int lgetc(HANDLE fh)
  1570.     
  1571.     
  1572.     ARGUMENTS:
  1573.     
  1574.         fh      - File handle for an input file
  1575.     
  1576.     
  1577.     RETURN VALUE:
  1578.     
  1579.         Value of a character read from the file (0-255)
  1580.         EOF (-1) if end of file or an error condition occurs
  1581.     
  1582.     
  1583.     DESCRIPTION:
  1584.     
  1585.           This function reads a single character from an  input  file  using
  1586.        LOW LEVEL (unbuffered) I/O, and returns it as a positive value in the
  1587.        range of 0 to 255. A full 16 bit value is returned, allowing the  end
  1588.        of file condition to be distinct from the character value 255.
  1589.     
  1590.     
  1591.     EXAMPLES:
  1592.     
  1593.         if((c = lgetc(input_file)) == EOF)
  1594.             abort("End of file encountered\n");
  1595.     LGETS                                                             LGETS
  1596.     
  1597.     
  1598.     
  1599.     PROTOTYPE:
  1600.     
  1601.         char *lgets(char *buffer, int size, HANDLE fh)
  1602.     
  1603.     
  1604.     ARGUMENTS:
  1605.     
  1606.         buffer  - Pointer to string to receive line
  1607.         size    - Maximum size of line to read
  1608.         fh      - File handle of an input file
  1609.     
  1610.     
  1611.     RETURN VALUE:
  1612.     
  1613.         Pointer to "buffer", or 0 if end of file
  1614.     
  1615.     
  1616.     DESCRIPTION:
  1617.     
  1618.           The "lgets" function reads characters  from  the  specified  input
  1619.        file using LOW  LEVEL  (unbuffered)  I/O,  and  places  them  in  the
  1620.        character buffer until one of three things happens:
  1621.     
  1622.           1) A NEWLINE character is encountered.
  1623.     
  1624.           2) The END of the file is encountered.
  1625.     
  1626.           3) The limit of "size" characters are read.
  1627.     
  1628.           The string is terminated with the standard  NULL  (00)  character.
  1629.        The trailing NEWLINE '\n' character is NOT  included  in  the  output
  1630.        buffer.
  1631.     
  1632.     
  1633.     EXAMPLES:
  1634.     
  1635.         lgets(input_line, 80, L_stdin);
  1636.     LONGJMP                                                         LONGJMP
  1637.     
  1638.     
  1639.     
  1640.     PROTOTYPE:
  1641.     
  1642.         longjmp(int savenv[3], int rvalue)
  1643.     
  1644.     
  1645.     ARGUMENTS:
  1646.     
  1647.         savenv  - Save area for program context
  1648.         rvalue  - Value to be returned by "setjmp"
  1649.     
  1650.     
  1651.     RETURN VALUE:
  1652.     
  1653.         N/A - Function never returns
  1654.     
  1655.     
  1656.     DESCRIPTION:
  1657.     
  1658.           The  "longjmp"  function  causes  execution  to  transfer  to  the
  1659.        "setjmp" call which  set  up  the  "savenv"  variable.  The  "setjmp"
  1660.        function will appear to return the value of "rvalue".
  1661.     
  1662.           NOTE-1: "longjmp" may  only  be  used  from  within  the  function
  1663.        calling "setjmp" or a function which has been called  "beneath"  that
  1664.        function. IT MUST NOT BE USED AFTER THE FUNCTION CALLING "SETJMP" HAS
  1665.        TERMINATED.
  1666.     
  1667.           NOTE-2: If "rvalue" is zero, the function  calling  "setjmp"  will
  1668.        assume that it is returning from initialization. Unless you want this
  1669.        unusual behavior, you should not pass  a  return  value  of  zero  to
  1670.        "longjmp".
  1671.     
  1672.           See also SETJMP.
  1673.     
  1674.     
  1675.     EXAMPLES:
  1676.     
  1677.         if(getc(stdin) == ('C'-'@'))    /* If Control-C entered... */
  1678.             longjmp(savearea, 1);       /* Return to main function */
  1679.     LPRINTF                                                         LPRINTF
  1680.     
  1681.     
  1682.     
  1683.     PROTOTYPE:
  1684.     
  1685.         register lprintf(int handle, char *format, arg, ...)
  1686.     
  1687.     
  1688.     ARGUMENTS:
  1689.     
  1690.         handle  - DOS file handle of output file
  1691.         format  - Pointer to format string
  1692.         arg     - Argument as determined by format string
  1693.         ...     - Additional arguments may be required
  1694.     
  1695.     
  1696.     RETURN VALUE:
  1697.     
  1698.         None
  1699.     
  1700.     
  1701.     DESCRIPTION:
  1702.     
  1703.           This routine performs a formatted print to  a  file  specified  by
  1704.        'fh', using LOW LEVEL (unbuffered) I/O.
  1705.     
  1706.           The 'format' string is written to  the  file  with  the  arguments
  1707.        substituted for special "conversion characters".  See  "fprintf"  for
  1708.        more information on format strings and conversions.
  1709.     
  1710.           NOTE: This function uses a variable number of arguments, and  must
  1711.        be declared as "register" (See "stdio.h").
  1712.     
  1713.     
  1714.     EXAMPLES:
  1715.     
  1716.         lprintf(fh, "Total errors=%u", error_count);
  1717.     LPUTC                                                             LPUTC
  1718.     
  1719.     
  1720.     
  1721.     PROTOTYPE:
  1722.     
  1723.         lputc(char c, HANDLE fh)
  1724.     
  1725.     
  1726.     ARGUMENTS:
  1727.     
  1728.         c       - Any character value
  1729.         fh      - File handle of an output file
  1730.     
  1731.     
  1732.     RETURN VALUE:
  1733.     
  1734.         0 if successful, otherwise an operating system error code
  1735.     
  1736.     
  1737.     DECRIPTION:
  1738.     
  1739.           This function writes the character 'c' to the  file  indicated  by
  1740.        'fh' using LOW LEVEL (unbuffered) I/O. The "newline"  (\n)  character
  1741.        will be translated into whatever character(s)  are  required  by  the
  1742.        operating system to separate records in the file.
  1743.     
  1744.     
  1745.     EXAMPLES:
  1746.     
  1747.         lputc('*', fh);
  1748.         lputc('\n', L_stderr);
  1749.     LPUTS                                                             LPUTS
  1750.     
  1751.     
  1752.     
  1753.     PROTOTYPE:
  1754.     
  1755.         lputs(char *string, HANDLE fh)
  1756.     
  1757.     
  1758.     ARGUMENTS:
  1759.     
  1760.         string  - Pointer to a character string
  1761.         fh      - File handle of an output file
  1762.     
  1763.     
  1764.     RETURN VALUE:
  1765.     
  1766.         0 if successful, otherwise an operating system error code
  1767.     
  1768.     
  1769.     DESCRIPTION:
  1770.     
  1771.           The "lputs" function writes the specified string to the  indicated
  1772.        output file using LOW LEVEL (unbuffered) I/O.  The  zero  terminating
  1773.        the string is NOT written.
  1774.     
  1775.     
  1776.     EXAMPLES:
  1777.     
  1778.         lputs("Text message", output_fh);
  1779.     LREWIND                                                         LREWIND
  1780.     
  1781.     
  1782.     
  1783.     PROTOTYPE:
  1784.     
  1785.         int lrewind(HANDLE fh)
  1786.     
  1787.     
  1788.     ARGUMENTS:
  1789.     
  1790.         fh      - File handle of an open file
  1791.     
  1792.     
  1793.     RETURN VALUE:
  1794.     
  1795.         0 if successful, otherwise an operating system error code
  1796.     
  1797.     
  1798.     DESCRIPTION:
  1799.     
  1800.           This function resets the operating system internal file handle  so
  1801.        than any subsequent read or writes will be at the  beginning  of  the
  1802.        file. For use with LOW LEVEL (unbuffered) file I/O only.
  1803.     
  1804.     
  1805.     EXAMPLES:
  1806.     
  1807.         lrewind(input_fh);
  1808.     LSCANF                                                           LSCANF
  1809.     
  1810.     
  1811.     
  1812.     PROTOTYPE:
  1813.     
  1814.         register int lscanf(int fh, char *format, &arg, ...)
  1815.     
  1816.     
  1817.     ARGUMENTS:
  1818.     
  1819.         fh      - DOS file handle of input file
  1820.         format  - Pointer to format string
  1821.         arg     - Argument as determined by format string
  1822.         ...     - Additional arguments may be required
  1823.     
  1824.     
  1825.     RETURN VALUE:
  1826.     
  1827.         The number of successful matches
  1828.         EOF (-1) if end of file or an error condition occurs
  1829.     
  1830.     
  1831.     DESCRIPTION:
  1832.     
  1833.           This routine reads a line from the specified file using LOW  LEVEL
  1834.        (unbuffered) I/O, and scans it for specific  values  which  are  then
  1835.        assigned to the  passed  argument  addresses.  The  types  of  values
  1836.        scanned are determined by special "conversion characters" within  the
  1837.        "format" string.
  1838.     
  1839.           See "fscanf" for more information on format strings.
  1840.     
  1841.           NOTE: This function uses a variable number of arguments, and  must
  1842.        be declared as "register".
  1843.     
  1844.     
  1845.     EXAMPLES:
  1846.     
  1847.         if(lscanf(infile,"%s %s %u", first_name, last_name, &age) != 3)
  1848.             abort("Error in user record\n");
  1849.     LSEEK                                                             LSEEK
  1850.     
  1851.     
  1852.     
  1853.     PROTOTYPE:
  1854.     
  1855.         (1) int lseek(HANDLE fh, int h_offset, unsigned l_offset, int mode)
  1856.         (2) int lseek(HANDLE fh, int offset, mode)
  1857.     
  1858.     
  1859.     ARGUMENTS:
  1860.     
  1861.         fh  - File handle of an open file
  1862.         h_offset- Highest 16 bits of offset value
  1863.         l_offset- Lowest 16 bits of offset value
  1864.         offset  - 16 bit offset value
  1865.         mode    - Type of seek
  1866.                     0 = Absolute from start of file
  1867.                     1 = Signed offset from current position
  1868.                     2 = Signed offset from end of file
  1869.     
  1870.     
  1871.     RETURN VALUE:
  1872.     
  1873.         0 if successful, otherwise an operating system error code
  1874.     
  1875.     
  1876.     DESCRIPTION:
  1877.     
  1878.           This function positions the operating system internal pointer into
  1879.        a file so that any read or write will take  place  at  the  specified
  1880.        position in the file.
  1881.     
  1882.           Most operating systems which support files of > 64K bytes in  size
  1883.        will support form (1) of the function, using both high and low offset
  1884.        values.
  1885.     
  1886.           Smaller operating  systems  may  only  support  form  (2)  of  the
  1887.        function, allowing seeking of only +/- 32K bytes.
  1888.     
  1889.           Also, some implementations may not support  all  "modes",  or  may
  1890.        only allow unsigned (positive) offsets.
  1891.     
  1892.           For use with LOW LEVEL (unbuffered I/O only).
  1893.     
  1894.     
  1895.     EXAMPLES:
  1896.     
  1897.         lseek(input_fh, 0, 2);  /* Advance to end of file */
  1898.     LTELL                                                             LTELL
  1899.     
  1900.     
  1901.     
  1902.     PROTOTYPE:
  1903.     
  1904.         (1) int ltell(HANDLE fh, int &h_offset, unsigned &l_offset)
  1905.         (2) int ltell(HANDLE fh, int &offset)
  1906.     
  1907.     
  1908.     ARGUMENTS:
  1909.     
  1910.         fh      - File handle of an open file
  1911.         h_offset- Address of int to receive high word of offset
  1912.         l_offset- Address of int to receive low word of offset
  1913.         offset  - Address of int to receive offset
  1914.     
  1915.     
  1916.     RETURN VALUE:
  1917.     
  1918.         0 if successful, otherwise an operating system error code
  1919.     
  1920.     
  1921.     DESCRIPTION:
  1922.     
  1923.           This function gets the current read/write position within a  file.
  1924.        The position returned indicates the absolute character (byte)  offset
  1925.        from the start of the file where the next read  or  write  will  take
  1926.        place.
  1927.     
  1928.           Most operating systems which support files of > 64K bytes in  size
  1929.        will support form (1) of the function, returning both  high  and  low
  1930.        offset values.
  1931.     
  1932.           Smaller operating  systems  may  only  support  form  (2)  of  the
  1933.        function,  allowing  access  to  only  the  first   65535   character
  1934.        positions.
  1935.     
  1936.           For use with LOW LEVEL (unbuffered I/O only).
  1937.     
  1938.     
  1939.     EXAMPLES:
  1940.     
  1941.         ltell(fp, &oldh, &oldl);    /* Save file position */
  1942.             . . .                   /* Perform some operations on the file */
  1943.         lseek(fp, oldh, oldl, 0);   /* Return to previous position */
  1944.     MALLOC                                                           MALLOC
  1945.     
  1946.     
  1947.     
  1948.     PROTOTYPE:
  1949.     
  1950.         char *malloc(int size)
  1951.     
  1952.     
  1953.     ARGUMENTS:
  1954.     
  1955.         size    - Size of memory block to allocate (in bytes).
  1956.     
  1957.     
  1958.     RETURN VALUE:
  1959.     
  1960.         0       - Memory allocation failed
  1961.         !0      - Pointer to allocated memory block
  1962.     
  1963.     
  1964.     DESCRIPTION:
  1965.     
  1966.           The "malloc" function allocates a block of memory of the specified
  1967.        size from the heap, and returns a pointer to  it.  This  memory  will
  1968.        remain allocated until it is  explicitly  releases  with  the  "free"
  1969.        function.
  1970.     
  1971.     
  1972.     EXAMPLES:
  1973.     
  1974.         if(!(ptr = malloc(BUFSIZ)))     /* Allocate a temporary buffer */
  1975.             abort("Not enough memory");
  1976.         do {                            /* Copy the file over */
  1977.             size = fread(ptr, BUFSIZ, in_fp);
  1978.             fwrite(ptr, size, out_fp); }
  1979.         while(size == BUFSIZ);
  1980.         free(ptr);                      /* Release temporary buffer */
  1981.     MAX                                                                 MAX
  1982.     
  1983.     
  1984.     
  1985.     PROTOTYPE:
  1986.     
  1987.         int max(int value1, int value2)
  1988.     
  1989.     
  1990.     ARGUMENTS:
  1991.     
  1992.         value1  - Any integer value
  1993.         value2  - Any integer value
  1994.     
  1995.     
  1996.     RETURN VALUE:
  1997.     
  1998.         The greater of "value1" or "value2"
  1999.     
  2000.     
  2001.     DESCRIPTION:
  2002.     
  2003.           The "max" function returns the higher of its two argument values.
  2004.     
  2005.     
  2006.     EXAMPLES:
  2007.     
  2008.         biggest = max(a, b);
  2009.     MEMCPY                                                           MEMCPY
  2010.     
  2011.     
  2012.     
  2013.     PROTOTYPE:
  2014.     
  2015.         memcpy(char *dest, char *source, unsigned size)
  2016.     
  2017.     
  2018.     ARGUMENTS:
  2019.     
  2020.         dest    - Pointer to the destination
  2021.         source  - Pointer to the souce
  2022.         size    - Number of bytes to copy
  2023.     
  2024.     
  2025.     RETURN VALUE:
  2026.     
  2027.         None
  2028.     
  2029.     
  2030.     DESCRIPTION:
  2031.     
  2032.           The "memcpy" function will copy the specified number of bytes from
  2033.        the source to the destination.
  2034.     
  2035.     
  2036.     EXAMPLES:
  2037.     
  2038.         memcpy(buffer1, buffer2, 256);
  2039.     MEMSET                                                           MEMSET
  2040.     
  2041.     
  2042.     
  2043.     PROTOTYPE:
  2044.     
  2045.         memset(char *block, char value, unsigned size)
  2046.     
  2047.     
  2048.     ARGUMENTS:
  2049.     
  2050.         block   - Pointer to a block of memory
  2051.         value   - Value to initialize memory with
  2052.         size    - Number of bytes to initialize
  2053.     
  2054.     
  2055.     RETURN VALUE:
  2056.     
  2057.         None
  2058.     
  2059.     
  2060.     DESCRIPTION:
  2061.     
  2062.           Sets a block of memory  beginning  at  the  pointer  "block",  for
  2063.        "size" bytes to the byte value "value".
  2064.     
  2065.     
  2066.     EXAMPLES:
  2067.     
  2068.         memset(buffer, 0, 100);
  2069.     MIN                                                                 MIN
  2070.     
  2071.     
  2072.     
  2073.     PROTOTYPE:
  2074.     
  2075.         int min(int value1, int value2)
  2076.     
  2077.     
  2078.     ARGUMENTS:
  2079.     
  2080.         value1  - Any integer value
  2081.         value2  - Any integer value
  2082.     
  2083.     
  2084.     RETURN VALUE:
  2085.     
  2086.         The smaller of "value1" or "value2"
  2087.     
  2088.     
  2089.     DESCRIPTION:
  2090.     
  2091.           The "min" function returns the lower of its two argument values.
  2092.     
  2093.     
  2094.     EXAMPLES:
  2095.     
  2096.         least = min(a, b);
  2097.     MKDIR                                                             MKDIR
  2098.     
  2099.     
  2100.     
  2101.     PROTOTYPE:
  2102.     
  2103.         int mkdir(char *pathname)
  2104.     
  2105.     
  2106.     ARGUMENTS:
  2107.     
  2108.         pathname- Name of directory to create
  2109.     
  2110.     
  2111.     RETURN VALUE:
  2112.     
  2113.         0 if successful, otherwise an operating system error code
  2114.     
  2115.     
  2116.     DESCRIPTION:
  2117.     
  2118.           The "mkdir" function create a new directory on the disk under  the
  2119.        specified path name.
  2120.     
  2121.     
  2122.     EXAMPLES:
  2123.     
  2124.         mkdir("subdir");
  2125.     NARGS                                                             NARGS
  2126.     
  2127.     
  2128.     
  2129.     PROTOTYPE:
  2130.     
  2131.         int nargs()
  2132.     
  2133.     
  2134.     ARGUMENTS:
  2135.     
  2136.         None
  2137.     
  2138.     
  2139.     RETURN VALUE:
  2140.     
  2141.         The number of arguments passed to the calling function
  2142.     
  2143.     
  2144.     DESCRIPTION:
  2145.     
  2146.           Returns the number of arguments passed to a "register" function.
  2147.     
  2148.           NOTE: When  calling  a  "register"  function,  MICRO-C  loads  the
  2149.        accumulator with the number of arguments just prior  to  calling  the
  2150.        function. This "nargs" routine is  simply  a  null  definition  which
  2151.        returns with the same value in the accumulator as was there  when  it
  2152.        was called. Therefore "nargs" MUST BE  THE  FIRST  ARITHMETIC  ENTITY
  2153.        EVALUATED WITHIN  THE  REGISTER  FUNCTION  or  the  contents  of  the
  2154.        accumulator will be lost. Some examples of "register" definitions and
  2155.        the use of "nargs" may be found in the library source code.
  2156.     
  2157.     
  2158.     EXAMPLES:
  2159.     
  2160.         first_arg = nargs() * 2 + &arguments;
  2161.     OPEN                                                               OPEN
  2162.     
  2163.     
  2164.     
  2165.     PROTOTYPE:
  2166.     
  2167.         HANDLE open(char *filename, int options)
  2168.     
  2169.     
  2170.     ARGUMENTS:
  2171.     
  2172.         filename- Name of the file to open
  2173.         options - Open options (defined in file.h)
  2174.     
  2175.     
  2176.     RETURN VALUE:
  2177.     
  2178.         File handle for the open file
  2179.         Zero (0) if file could not be opened
  2180.     
  2181.     
  2182.     DESCRIPTION:
  2183.     
  2184.           This function  open  a  file  for  direct  access  via  LOW  LEVEL
  2185.        (unbuffered) I/O.
  2186.     
  2187.     
  2188.     EXAMPLES:
  2189.     
  2190.         if(fh = open("data.img", F_READ)) {
  2191.             read(data_buf, 100, fh);
  2192.             close(fh); }
  2193.         else
  2194.             abort("Unable to read data file");
  2195.     OUT                                                                 OUT
  2196.     
  2197.     
  2198.     
  2199.     PROTOTYPE:
  2200.     
  2201.         out(unsigned port, int value)
  2202.     
  2203.     
  2204.     ARGUMENTS:
  2205.     
  2206.         port    - I/O port address
  2207.         value   - Value to write to I/O port
  2208.     
  2209.     
  2210.     RETURN VALUE:
  2211.     
  2212.         None
  2213.     
  2214.     
  2215.     DESCRIPTION:
  2216.     
  2217.           The "out" function writes a byte (8 bit) value to an I/O port.
  2218.     
  2219.           The valid range of values for "port" depends on  the  I/O  address
  2220.        space of the processor.
  2221.     
  2222.           This function is not provided for processors which do not  support
  2223.        a separate I/O address space.
  2224.     
  2225.     
  2226.     EXAMPLES:
  2227.     
  2228.         out(0, 0);      /* Output 0 to I/O port 0 */
  2229.     OUTW                                                               OUTW
  2230.     
  2231.     
  2232.     
  2233.     PROTOTYPE:
  2234.     
  2235.         outw(unsigned port, int value)
  2236.     
  2237.     
  2238.     ARGUMENTS:
  2239.     
  2240.         port    - I/O port address
  2241.         value   - Value to write to I/O port
  2242.     
  2243.     
  2244.     RETURN VALUE:
  2245.     
  2246.         None
  2247.     
  2248.     
  2249.     DESCRIPTION:
  2250.     
  2251.           The "outw" function writes a word (16 bit) value to an I/O port.
  2252.     
  2253.           The valid range of values for "port" depends on  the  I/O  address
  2254.        space of the processor.
  2255.     
  2256.           This function is not provided for processors which do not  support
  2257.        a separate I/O address space.
  2258.     
  2259.     
  2260.     EXAMPLES:
  2261.     
  2262.         outw(0, 0);     /* Write 0 to I/O ports 0 and 1 */
  2263.     PEEK                                                               PEEK
  2264.     
  2265.     
  2266.     
  2267.     PROTOTYPE:
  2268.     
  2269.         (1) int peek(unsigned address)
  2270.         (2) int peek(unsigned h_addr, unsigned l_addr)
  2271.         (3) int peek(unsigned segment, unsigned offset)
  2272.     
  2273.     
  2274.     ARGUMENTS:
  2275.     
  2276.         segment - Memory segment
  2277.         offset  - Offset into segment
  2278.         h_addr  - High word of memory address
  2279.         l_addr  - Low word of memory address
  2280.         address - 16 bit memory address
  2281.     
  2282.     
  2283.     RETURN VALUE:
  2284.     
  2285.         The 8 bit value read from the given memory address
  2286.     
  2287.     
  2288.     DESCRIPTION:
  2289.     
  2290.           The "peek" function reads and returns a byte (8 bits) from  memory
  2291.        as an integer value between 0 and 255.
  2292.     
  2293.           Processors such as the 8080 or 6809 which address 64K of memory or
  2294.        less use form (1) of the function.
  2295.     
  2296.           Non-segmented processors addressing more  than  64K  such  as  the
  2297.        68000 use form (2) of the function.
  2298.     
  2299.           Processors employing a "segmented" architecture such as  the  8086
  2300.        use form (3) of the function.
  2301.     
  2302.     
  2303.     EXAMPLES:
  2304.     
  2305.         while(peek(0)); /* Wait for flag to clear */
  2306.     PEEKW                                                             PEEKW
  2307.     
  2308.     
  2309.     
  2310.     PROTOTYPE:
  2311.     
  2312.         (1) int peekw(unsigned address)
  2313.         (2) int peekw(unsigned h_addr, unsigned l_addr)
  2314.         (3) int peekw(unsigned segment, unsigned offset)
  2315.     
  2316.     
  2317.     ARGUMENTS:
  2318.     
  2319.         segment - Memory segment
  2320.         offset  - Offset into segment
  2321.         h_addr  - High word of memory address
  2322.         l_addr  - Low word of memory address
  2323.         address - 16 bit memory address
  2324.     
  2325.     
  2326.     RETURN VALUE:
  2327.     
  2328.         The 16 bit value read from the given memory address
  2329.     
  2330.     
  2331.     DESCRIPTION:
  2332.     
  2333.           The "peekw" function reads and  returns  a  word  (16  bits)  from
  2334.        memory as an integer value between 0 and 65535 (-1).
  2335.     
  2336.           Processors such as the 8080 or 6809 which address 64K of memory or
  2337.        less use form (1) of the function.
  2338.     
  2339.           Non-segmented processors addressing more  than  64K  such  as  the
  2340.        68000 use form (2) of the function.
  2341.     
  2342.           Processors employing a "segmented" architecture such as  the  8086
  2343.        use form (3) of the function.
  2344.     
  2345.     
  2346.     EXAMPLES:
  2347.     
  2348.         var = peekw(0));
  2349.     POKE                                                               POKE
  2350.     
  2351.     
  2352.     
  2353.     PROTOTYPE:
  2354.     
  2355.         (1) poke(unsigned address, int value)
  2356.         (2) poke(unsigned h_addr, unsigned l_addr, int value)
  2357.         (3) poke(unsigned segment, unsigned offset, int value)
  2358.     
  2359.     
  2360.     ARGUMENTS:
  2361.     
  2362.         segment - Memory segment
  2363.         offset  - Offset into segment
  2364.         h_addr  - High word of memory address
  2365.         l_addr  - Low word of memory address
  2366.         address - 16 bit memory address
  2367.         value   - Value to be written to memory
  2368.     
  2369.     
  2370.     RETURN VALUE:
  2371.     
  2372.         None
  2373.     
  2374.     
  2375.     DESCRIPTION:
  2376.     
  2377.           The "poke" function writes a byte (8 bit) value to memory.
  2378.     
  2379.           Processors such as the 8080 or 6809 which address 64K of memory or
  2380.        less use form (1) of the function.
  2381.     
  2382.           Non-segmented processors addressing more  than  64K  such  as  the
  2383.        68000 use form (2) of the function.
  2384.     
  2385.           Processors employing a "segmented" architecture such as  the  8086
  2386.        use form (3) of the function.
  2387.     
  2388.     
  2389.     EXAMPLES:
  2390.     
  2391.         poke(0, 0);     /* Write 0 to location 0 */
  2392.     POKEW                                                             POKEW
  2393.     
  2394.     
  2395.     
  2396.     PROTOTYPE:
  2397.     
  2398.         (1) pokew(unsigned address, int value)
  2399.         (2) pokew(unsigned h_addr, unsigned l_addr, int value)
  2400.         (3) pokew(unsigned segment, unsigned offset, int value)
  2401.     
  2402.     
  2403.     ARGUMENTS:
  2404.     
  2405.         segment - Memory segment
  2406.         offset  - Offset into segment
  2407.         h_addr  - High word of memory address
  2408.         l_addr  - Low word of memory address
  2409.         address - 16 bit memory address
  2410.         value   - Value to be written to memory
  2411.     
  2412.     
  2413.     RETURN VALUE:
  2414.     
  2415.         None
  2416.     
  2417.     
  2418.     DESCRIPTION:
  2419.     
  2420.           The "pokew" function writes a word (16 bit) value to memory.
  2421.     
  2422.           Processors such as the 8080 or 6809 which address 64K of memory or
  2423.        less use form (1) of the function.
  2424.     
  2425.           Non-segmented processors addressing more  than  64K  such  as  the
  2426.        68000 use form (2) of the function.
  2427.     
  2428.           Processors employing a "segmented" architecture such as  the  8086
  2429.        use form (3) of the function.
  2430.     
  2431.     
  2432.     EXAMPLES:
  2433.     
  2434.         pokew(0, 0);    /* Write 0 to locations 0 and 1 */
  2435.     PRINTF                                                           PRINTF
  2436.     
  2437.     
  2438.     
  2439.     PROTOTYPE:
  2440.     
  2441.         register printf(char *format, arg, ...)
  2442.     
  2443.     
  2444.     ARGUMENTS:
  2445.     
  2446.         format  - Pointer to format string
  2447.         arg     - Argument as determined by format string
  2448.         ...     - Additional arguments may be required
  2449.     
  2450.     
  2451.     RETURN VALUE:
  2452.     
  2453.         None
  2454.     
  2455.     
  2456.     DESCRIPTION:
  2457.     
  2458.           The "printf" routine performs a formatted print  to  the  standard
  2459.        output device  (usually  system  console).  The  "format"  string  is
  2460.        written  with  the  arguments  substituted  for  special  "conversion
  2461.        characters".
  2462.     
  2463.           See "fprintf" for more information on format strings.
  2464.     
  2465.           NOTE: This function uses a variable number of arguments, and  must
  2466.        be declared as "register" (See "stdio.h").
  2467.     
  2468.     
  2469.     EXAMPLES:
  2470.     
  2471.         printf("Hello world!!!\n");
  2472.         printf("File '%s', has %u lines\n", filename, num_lines);
  2473.     PUTC                                                               PUTC
  2474.     
  2475.     
  2476.     
  2477.     PROTOTYPE:
  2478.     
  2479.         putc(char c, FILE *fp)
  2480.     
  2481.     
  2482.     ARGUMENTS:
  2483.     
  2484.         c       - Any character value
  2485.         fp      - File pointer to an output file
  2486.     
  2487.     
  2488.     RETURN VALUE:
  2489.     
  2490.         0 if successful, otherwise an operating system error code
  2491.     
  2492.     
  2493.     DECRIPTION:
  2494.     
  2495.           This function writes the character 'c' to the  file  indicated  by
  2496.        the file pointer 'fp'.
  2497.     
  2498.     
  2499.     EXAMPLES:
  2500.     
  2501.         putc('*', fp);
  2502.         putc('\n', stderr);
  2503.     RAND                                                               RAND
  2504.     
  2505.     
  2506.     
  2507.     PROTOTYPE:
  2508.     
  2509.         unsigned rand(unsigned limit)
  2510.     
  2511.     
  2512.     ARGUMENTS:
  2513.     
  2514.         limit   - Maximum value to return
  2515.     
  2516.     
  2517.     RETURN VALUE:
  2518.     
  2519.         A pseudo-random number in the range of 0 to (limit-1)
  2520.     
  2521.     
  2522.     DESCRIPTION:
  2523.     
  2524.           The "rand" function calculates the next value of  a  pseudo-random
  2525.        sequence, based on a 16 bit unsigned "seed" value, which it maintains
  2526.        in the global variable "RAND_SEED". The new value is  stored  as  the
  2527.        new seed value, and is then divided  by  the  "limit"  parameter,  to
  2528.        obtain the remainder, which is returned. This  results  in  a  random
  2529.        number in the range of zero (0) to (limit - 1).
  2530.     
  2531.           Any  particular  sequence  may  be  repeated,  by   reseting   the
  2532.        "RAND_SEED" value.
  2533.     
  2534.     
  2535.     EXAMPLES:
  2536.     
  2537.         value = rand(52);
  2538.     READ                                                               READ
  2539.     
  2540.     
  2541.     
  2542.     PROTOTYPE:
  2543.     
  2544.         int read(char *buffer, int size, HANDLE fh)
  2545.     
  2546.     
  2547.     ARGUMENTS:
  2548.     
  2549.         buffer  - Pointer to buffer to receive data
  2550.         size    - Number of bytes to read
  2551.         fh      - File handle of an input file
  2552.     
  2553.     
  2554.     RETURN VALUE:
  2555.     
  2556.         Number of bytes read from file
  2557.     
  2558.     
  2559.     DESCRIPTION:
  2560.     
  2561.           This function reads a block of data from a file  using  LOW  LEVEL
  2562.        (unbuffered) I/O, and places it in memory at the address of "buffer".
  2563.        Data is read in "raw"  form,  with  no  interpretation  of  "newline"
  2564.        characters etc. If the number of bytes  returned  is  less  than  the
  2565.        number of bytes requested, either the end of the file was encountered
  2566.        or an error condition occured (in which case the value will be zero).
  2567.     
  2568.     
  2569.     EXAMPLES:
  2570.     
  2571.         read(block, 512, input_fh);
  2572.     RENAME                                                           RENAME
  2573.     
  2574.     
  2575.     
  2576.     PROTOTYPE:
  2577.     
  2578.         int rename(char *pathname, char *newname)
  2579.     
  2580.     
  2581.     ARGUMENTS:
  2582.     
  2583.         pathname- Name of file to rename
  2584.         newname - New name for file
  2585.     
  2586.     
  2587.     RETURN VALUE:
  2588.     
  2589.         0 if successful, otherwise an operating system error code
  2590.     
  2591.     
  2592.     DESCRIPTION:
  2593.     
  2594.           This function changes the name of an existing file  to  the  ASCII
  2595.        string specified by newname.
  2596.     
  2597.     
  2598.     EXAMPLES:
  2599.     
  2600.         rename("output.dat", "output.bak");
  2601.     REWIND                                                           REWIND
  2602.     
  2603.     
  2604.     
  2605.     PROTOTYPE:
  2606.     
  2607.         int rewind(FILE *fp)
  2608.     
  2609.     
  2610.     ARGUMENTS:
  2611.     
  2612.         fp      - File pointer to an open file
  2613.     
  2614.     
  2615.     RETURN VALUE:
  2616.     
  2617.         0 if successful, otherwise an operating system error code
  2618.     
  2619.     
  2620.     DESCRIPTION:
  2621.     
  2622.           This function resets the operating system internal file pointer so
  2623.        than any subsequent read or writes will be at the  beginning  of  the
  2624.        file.
  2625.     
  2626.     
  2627.     EXAMPLES:
  2628.     
  2629.         rewind(input_file);
  2630.     RMDIR                                                             RMDIR
  2631.     
  2632.     
  2633.     
  2634.     PROTOTYPE:
  2635.     
  2636.         int rmdir(char *pathname)
  2637.     
  2638.     
  2639.     ARGUMENTS:
  2640.     
  2641.         pathname- Name of directory to delete
  2642.     
  2643.     
  2644.     RETURN VALUE:
  2645.     
  2646.         0 if successful, otherwise an operating system error code
  2647.     
  2648.     
  2649.     DESCRIPTION:
  2650.     
  2651.           This function removes a directory from the disk. On most  systems,
  2652.        the directory  must  be  empty  (contains  no  files)  otherwise  the
  2653.        function will fail.
  2654.     
  2655.     
  2656.     EXAMPLES:
  2657.     
  2658.         rmdir("subdir");
  2659.     SCANF                                                             SCANF
  2660.     
  2661.     
  2662.     
  2663.     PROTOTYPE:
  2664.     
  2665.         register int scanf(char *format, arg1, arg2, ...)
  2666.     
  2667.     
  2668.     ARGUMENTS:
  2669.     
  2670.         format  - Pointer to format string
  2671.         arg     - Argument as determined by format string
  2672.         ...     - Additional arguments may be required
  2673.     
  2674.     
  2675.     RETURN VALUE:
  2676.     
  2677.         The number of successful matches
  2678.         EOF (-1) if end of file or an error condition occurs
  2679.     
  2680.     
  2681.     DESCRIPTION:
  2682.     
  2683.           The "scanf" function reads and scans  a  line  from  the  standard
  2684.        input device (usually system console) for specific values. Values are
  2685.        read and assigned to  the  passed  argument  addresses  according  to
  2686.        special "conversion characters" in the "format" string.
  2687.     
  2688.           See "fscanf" for more information on format strings.
  2689.     
  2690.           NOTE: This function uses a variable number of arguments, and  must
  2691.        be declared as "register".
  2692.     
  2693.     
  2694.     EXAMPLES:
  2695.     
  2696.         do
  2697.             printf("Please enter your First & Last names, and your age?");
  2698.         while(scanf("%s %s %u", first_name, last_name, &age) != 3);
  2699.     SETBUF                                                           SETBUF
  2700.     
  2701.     
  2702.     
  2703.     PROTOTYPE:
  2704.     
  2705.         FILE *setbuf(FILE *fp, int size)
  2706.     
  2707.     
  2708.     ARGUMENTS:
  2709.     
  2710.         fp      - File pointer to an open file
  2711.         size    - Size of new I/O buffer
  2712.     
  2713.     
  2714.     RETURN VALUE:
  2715.     
  2716.         If successful, a new file pointer is returned, and the old one
  2717.         is released. On failure the old file pointer is returned.
  2718.     
  2719.     
  2720.     DESCRIPTION:
  2721.     
  2722.           The "setbuf" function will adjust the size of the buffer used  for
  2723.        I/O operations on the indicated open file.
  2724.     
  2725.           This is the ONLY way to set the buffer size for  the  "stdin"  and
  2726.        "stdout" streams. If you change the size of the "stdout" buffer,  you
  2727.        must remember to "fflush(stdout)" before terminating,  otherwise  the
  2728.        last buffer contents may not be written.
  2729.     
  2730.           For file opened by "fopen",  the  buffer  size  may  be  set  more
  2731.        efficently by setting the value of the external  variable  "IOB_size"
  2732.        prior to calling "fopen".
  2733.     
  2734.           If "setbuf" is unable to allocate space for  the  new  buffer,  it
  2735.        will return the old file pointer unchanged.
  2736.     
  2737.     
  2738.     EXAMPLES:
  2739.     
  2740.         stdout = setbuf(stdout, 512);   /* Set stdout to 512 byte buffer */
  2741.     SETJMP                                                           SETJMP
  2742.     
  2743.     
  2744.     
  2745.     PROTOTYPE:
  2746.     
  2747.         int setjmp(int savenv[3])
  2748.     
  2749.     
  2750.     ARGUMENTS:
  2751.     
  2752.         savenv  - Save area for program context
  2753.     
  2754.     
  2755.     RETURN VALUE:
  2756.     
  2757.         0 is returned when actually called
  2758.         Value passed to "longjmp" is returned otherwise
  2759.     
  2760.     
  2761.     DESCRIPTION:
  2762.     
  2763.           When called, the "setjmp" function stores  the  current  execution
  2764.        state of the program into the passed integer array, and  returns  the
  2765.        value zero.
  2766.     
  2767.           The "longjmp" function may then be used to return the  program  to
  2768.        the "setjmp" call. In this case, the value returned by "setjmp"  will
  2769.        be the value which was passed to "longjmp". This allows the  function
  2770.        containing "setjmp" to determine which call to  "longjmp"  transfered
  2771.        execution to it.
  2772.     
  2773.           See also LONGJMP.
  2774.     
  2775.     
  2776.     EXAMPLES:
  2777.     
  2778.         switch(setjmp(savearea)) {
  2779.             case 0 : printf("Longjmp has been set up"); break;
  2780.             case 1 : printf("Control-C Interrupt");     break;
  2781.             case 2 : printf("Reset command executed");  break;
  2782.             default: printf("Software error trap");     break; }
  2783.     SPRINTF                                                         SPRINTF
  2784.     
  2785.     
  2786.     
  2787.     PROTOTYPE:
  2788.     
  2789.         register sprintf(char *dest, char *format, arg, ...)
  2790.     
  2791.     
  2792.     ARGUMENTS:
  2793.     
  2794.         dest    - Pointer to destination string
  2795.         format  - Pointer to format string
  2796.         arg     - Argument as determined by format string
  2797.         ...     - Additional arguments may be required
  2798.     
  2799.     
  2800.     RETURN VALUE:
  2801.     
  2802.         None
  2803.     
  2804.     
  2805.     DESCRIPTION:
  2806.     
  2807.           The "sprintf" routine performs a formatted print to  a  string  in
  2808.        memory. The "format" string is written to the destination string with
  2809.        the arguments substituted for special "conversion characters".
  2810.     
  2811.           See "fprintf" for more information on format strings.
  2812.     
  2813.           NOTE: This function uses a variable number of arguments, and  must
  2814.        be declared as "register" (See "stdio.h").
  2815.     
  2816.     
  2817.     EXAMPLES:
  2818.     
  2819.         sprintf(header_file, "/lib/%s.h", header_name);
  2820.     SQRT                                                               SQRT
  2821.     
  2822.     
  2823.     
  2824.     PROTOTYPE:
  2825.     
  2826.         int sqrt(unsigned value)
  2827.     
  2828.     
  2829.     ARGUMENTS:
  2830.     
  2831.         value   - Number for which to calculate square root
  2832.     
  2833.     
  2834.     RETURN VALUE:
  2835.     
  2836.         The integer square root (rounded up) of the argument value
  2837.     
  2838.     
  2839.     DESCRIPTION:
  2840.     
  2841.           The  SQRT  function  returns  the  smallest  number   which   when
  2842.        multiplied by itself will give a number equal to or larger  that  the
  2843.        argument value.
  2844.     
  2845.     
  2846.     EXAMPLES:
  2847.     
  2848.     /*
  2849.      * Draw a circle about point (x, y) of radus (r)
  2850.      */
  2851.     circle(x, y, r)
  2852.         int x, y, r;
  2853.     {
  2854.         int i, j, k, rs, lj;
  2855.     
  2856.         rs = (lj = r)*r;
  2857.         for(i=0; i <= r; ++i) {
  2858.             j = k = sqrt(rs - (i*i));
  2859.             do {
  2860.                 plot_xy(x+i, y+j);
  2861.                 plot_xy(x+i, y-j);
  2862.                 plot_xy(x-i, y+j);
  2863.                 plot_xy(x-i, y-j); }
  2864.             while(++j < lj);
  2865.             lj = k; }
  2866.     }
  2867.     SSCANF                                                           SSCANF
  2868.     
  2869.     
  2870.     
  2871.     PROTOTYPE:
  2872.     
  2873.         register int sscanf(char *input, char *format, arg1, arg2, ...)
  2874.     
  2875.     
  2876.     ARGUMENTS:
  2877.     
  2878.         input   - Pointer to input string
  2879.         format  - Pointer to format string
  2880.         arg     - Argument as determined by format string
  2881.         ...     - Additional arguments may be required
  2882.     
  2883.     
  2884.     RETURN VALUE:
  2885.     
  2886.         The number of successful matches
  2887.     
  2888.     
  2889.     DESCRIPTION:
  2890.     
  2891.           The "sscanf" function  scans  a  string  in  memory  for  specific
  2892.        values. Values are read and assigned to the passed argument addresses
  2893.        according to special "conversion characters" in the "format" string.
  2894.     
  2895.           See "fscanf" for more information on format strings.
  2896.     
  2897.           NOTE: This function uses a variable number of arguments, and  must
  2898.        be declared as "register".
  2899.     
  2900.     
  2901.     EXAMPLES:
  2902.     
  2903.         sscanf(pathname,"/%s/%s", directory, filename);
  2904.     STRBEG                                                           STRBEG
  2905.     
  2906.     
  2907.     
  2908.     PROTOTYPE:
  2909.     
  2910.         int strbeg(char *string1, char *string2)
  2911.     
  2912.     
  2913.     ARGUMENTS:
  2914.     
  2915.         string1 - Pointer to character string to test
  2916.         string2 - Pointer to character string to check for
  2917.     
  2918.     
  2919.     RETURN VALUE:
  2920.     
  2921.         0   - String1 does not begin with string2
  2922.         1   - String1 begins with string2
  2923.     
  2924.     
  2925.     DECRIPTION:
  2926.     
  2927.           Tests the passed "string1" to determine if it begins with the same
  2928.        data as is contained within "string2".
  2929.     
  2930.     
  2931.     EXAMPLES:
  2932.     
  2933.         if(strbeg(command, "delete"))
  2934.             delete_file(&command[6]);
  2935.     STRCAT                                                           STRCAT
  2936.     
  2937.     
  2938.     
  2939.     PROTOTYPE:
  2940.     
  2941.         char *strcat(char *dest, *source)
  2942.     
  2943.     
  2944.     ARGUMENTS:
  2945.     
  2946.         dest    - Pointer to destination string
  2947.         source  - Pointer to source string
  2948.     
  2949.     
  2950.     RETURN VALUE:
  2951.     
  2952.         Pointer to zero terminating destination string
  2953.     
  2954.     
  2955.     DESCRIPTION:
  2956.     
  2957.           This function concatinates the source string onto the tail of  the
  2958.        destination string. The destination string must be  large  enough  to
  2959.        hold the entire contents of both strings.
  2960.     
  2961.     
  2962.     EXAMPLES:
  2963.     
  2964.         strcat(program_name, ".c");
  2965.     STRCHR                                                           STRCHR
  2966.     
  2967.     
  2968.     
  2969.     PROTOTYPE:
  2970.     
  2971.         char *strchr(char *string, char chr)
  2972.     
  2973.     
  2974.     ARGUMENTS:
  2975.     
  2976.         string  - Pointer to a character string
  2977.         chr     - Character to look for
  2978.     
  2979.     
  2980.     RETURN VALUE:
  2981.     
  2982.         Pointer to the first occurance of 'chr' in 'string'
  2983.         Zero (0) if character was not found
  2984.     
  2985.     
  2986.     DECRIPTION:
  2987.     
  2988.           Searches  the  passed  string  got  the  first  occurance  of  the
  2989.        specified character. If the character is  found,  a  pointer  to  its
  2990.        position in the string is returned. If the character is not found,  a
  2991.        null pointer is returned.
  2992.     
  2993.           The null (0) character is treated as valid data by this  function,
  2994.        thus:
  2995.           strchr(string, 0);
  2996.     
  2997.        would return the position of the null terminator of the string.
  2998.     
  2999.     
  3000.     EXAMPLES:
  3001.     
  3002.         comma = strchr(buffer, ',');
  3003.     STRCMP                                                           STRCMP
  3004.     
  3005.     
  3006.     
  3007.     PROTOTYPE:
  3008.     
  3009.         int strcmp(char *string1, char *string2)
  3010.     
  3011.     
  3012.     ARGUMENTS:
  3013.     
  3014.         string1 - Pointer to first string
  3015.         string2 - Pointer to second string
  3016.     
  3017.     
  3018.     RETURN VALUE:
  3019.     
  3020.         0   - Strings match exactly
  3021.         1   - String1 is greater than string2
  3022.         -1  - String2 is greater than string1
  3023.     
  3024.     
  3025.     DESCRIPTION:
  3026.     
  3027.           This function compares two strings character by character. If  the
  3028.        two strings are identical, a zero  (0)  is  returned.  If  the  first
  3029.        string is greater than the second (as far as ASCII is  concerned),  a
  3030.        one (1) is returned. If the second string is greater, a negative  one
  3031.        (-1) is returned.
  3032.     
  3033.     
  3034.     EXAMPLES:
  3035.     
  3036.         if(!strcmp(command, "quit"))
  3037.             exit(0);
  3038.     STRCPY                                                           STRCPY
  3039.     
  3040.     
  3041.     
  3042.     PROTOTYPE:
  3043.     
  3044.         char *strcpy(char *dest, char *source)
  3045.     
  3046.     
  3047.     ARGUMENTS:
  3048.     
  3049.         dest    - Pointer to destination string
  3050.         souce   - Pointer to source string
  3051.     
  3052.     
  3053.     RETURN VALUE:
  3054.     
  3055.         Pointer to zero terminating destination string
  3056.     
  3057.     
  3058.     DESCRIPTION:
  3059.     
  3060.           This function copies the source string to the destination  string.
  3061.        All data is copied up to and including the zero byte which terminates
  3062.        the string. The destination string must be large enough to  hold  the
  3063.        entire source.
  3064.     
  3065.     
  3066.     EXAMPLES:
  3067.     
  3068.         strcpy(filename, argv[1]);
  3069.     STRLEN                                                           STRLEN
  3070.     
  3071.     
  3072.     
  3073.     PROTOTYPE:
  3074.     
  3075.         int strlen(char *string)
  3076.     
  3077.     
  3078.     ARGUMENTS:
  3079.     
  3080.         string  - Pointer to a character string
  3081.     
  3082.     
  3083.     RETURN VALUE:
  3084.     
  3085.         The length of the string
  3086.     
  3087.     
  3088.     DECRIPTION:
  3089.     
  3090.           Returns the length in character of the passed string.  The  length
  3091.        does not include the zero byte which terminates the string.
  3092.     
  3093.     
  3094.     EXAMPLES:
  3095.     
  3096.         length = strlen(command);
  3097.     STRNCAT                                                         STRNCAT
  3098.     
  3099.     
  3100.     
  3101.     PROTOTYPE:
  3102.     
  3103.         char *strncat(char *dest, *source, unsigned length)
  3104.     
  3105.     
  3106.     ARGUMENTS:
  3107.     
  3108.         dest    - Pointer to destination string
  3109.         source  - Pointer to source string
  3110.         length  - Maximum number of characters to copy
  3111.     
  3112.     
  3113.     RETURN VALUE:
  3114.     
  3115.         Pointer to zero terminating destination string
  3116.     
  3117.     
  3118.     DESCRIPTION:
  3119.     
  3120.           This function concatinates the source string onto the tail of  the
  3121.        destination string. If the source string exceeds  "length"  bytes  in
  3122.        size, only that many characters are copied.
  3123.     
  3124.     
  3125.     EXAMPLES:
  3126.     
  3127.         strncat(path, filename, 64);
  3128.     STRNCMP                                                         STRNCMP
  3129.     
  3130.     
  3131.     
  3132.     PROTOTYPE:
  3133.     
  3134.         int strncmp(char *string1, char *string2, unsigned length)
  3135.     
  3136.     
  3137.     ARGUMENTS:
  3138.     
  3139.         string1 - Pointer to first string
  3140.         string2 - Pointer to second string
  3141.         length  - Number of bytes to compare
  3142.     
  3143.     
  3144.     RETURN VALUE:
  3145.     
  3146.         0   - Strings match exactly
  3147.         1   - String1 is greater than string2
  3148.         -1  - String2 is greater than string1
  3149.     
  3150.     
  3151.     DESCRIPTION:
  3152.     
  3153.           This function compares two strings character  by  character  until
  3154.        either a difference is detected, or  "length"  characters  have  been
  3155.        compared. If the two string portions are identical,  a  zero  (0)  is
  3156.        returned. If the first string is greater than the second (as  far  as
  3157.        ASCII is concerned), a one (1) is returned. If the second  string  is
  3158.        greater, a negative one (-1) is returned.
  3159.     
  3160.     
  3161.     EXAMPLES:
  3162.     
  3163.         len = strlen(buffer) - 3;
  3164.         for(i=1; i < len; ++i)
  3165.             if(strncmp(&buffer[i], "***", 3)
  3166.                 abort("Found three stars\n");
  3167.     STRNCPY                                                         STRNCPY
  3168.     
  3169.     
  3170.     
  3171.     PROTOTYPE:
  3172.     
  3173.         strncpy(char *dest, char *source, unsigned length)
  3174.     
  3175.     
  3176.     ARGUMENTS:
  3177.     
  3178.         dest    - Pointer to destination string
  3179.         souce   - Pointer to source string
  3180.         length  - Number of bytes to copy
  3181.     
  3182.     
  3183.     RETURN VALUE:
  3184.     
  3185.         None
  3186.     
  3187.     
  3188.     DESCRIPTION:
  3189.     
  3190.           This function copies "length" characters from the source string to
  3191.        the  destination  string.  If  the  source  string  is  shorter  than
  3192.        "length", the destination string is padded with nulls. If the  source
  3193.        string is longer than "length", only that many characters are copied,
  3194.        and the destination string is NOT zero terminated.
  3195.     
  3196.     
  3197.     EXAMPLES:
  3198.     
  3199.         strncpy(filename, argv[1], 64);
  3200.     STRSTR                                                           STRSTR
  3201.     
  3202.     
  3203.     
  3204.     PROTOTYPE:
  3205.     
  3206.         char *strstr(char *string1, char *string2)
  3207.     
  3208.     
  3209.     ARGUMENTS:
  3210.     
  3211.         string1 - Pointer to character string to test
  3212.         string2 - Pointer to substring to search for
  3213.     
  3214.     
  3215.     RETURN VALUE:
  3216.     
  3217.         Pointer to substring, or 0 if not found
  3218.     
  3219.     
  3220.     DECRIPTION:
  3221.     
  3222.           Searches the passed "string1"  for  the  first  occurance  of  the
  3223.        passed "string2". If found,  a  pointer  to  the  beginning  of  that
  3224.        substring within "string1" is returned.
  3225.     
  3226.     
  3227.     EXAMPLES:
  3228.     
  3229.         if(ptr = strstr(command, "delete"))
  3230.             delete_file(&ptr[6]);
  3231.     SYSTEM                                                           SYSTEM
  3232.     
  3233.     
  3234.     
  3235.     PROTOTYPE:
  3236.     
  3237.         int system(char *command)
  3238.     
  3239.     
  3240.     ARGUMENTS:
  3241.     
  3242.         command - A system command to be executed
  3243.     
  3244.     
  3245.     RETURN VALUE:
  3246.     
  3247.         0 if successful, otherwise an operating system error code
  3248.     
  3249.     
  3250.     DESCRIPTION:
  3251.     
  3252.           The SYSTEM function accepts any  operating  system  command  as  a
  3253.        string parameter, and passes that command to the operating system  to
  3254.        be executed.
  3255.     
  3256.           When the command has terminated,  execution  will  resume  in  the
  3257.        MICRO-C program, with the statement following the call to SYSTEM.
  3258.     
  3259.     
  3260.     EXAMPLES:
  3261.     
  3262.         system("DEL *.TMP");
  3263.     TOLOWER                                                         TOLOWER
  3264.     
  3265.     
  3266.     
  3267.     PROTOTYPE:
  3268.     
  3269.         char tolower(char c)
  3270.     
  3271.     
  3272.     ARGUMENTS:
  3273.     
  3274.         c   - Any character value
  3275.     
  3276.     
  3277.     RETURN VALUE:
  3278.     
  3279.         The value of 'c', converted to lower case
  3280.     
  3281.     
  3282.     DESCRIPTION:
  3283.     
  3284.           Returns the value of 'c' converted to lower case. If 'c' is not  a
  3285.        letter of upper case, no change is made, and the  original  value  of
  3286.        'c' is returned.
  3287.     
  3288.     
  3289.     EXAMPLES:
  3290.     
  3291.         input_char = tolower(getc(stdin));
  3292.     TOUPPER                                                         TOUPPER
  3293.     
  3294.     
  3295.     
  3296.     PROTOTYPE:
  3297.     
  3298.         char toupper(char c)
  3299.     
  3300.     
  3301.     ARGUMENTS:
  3302.     
  3303.         c   - Any character value
  3304.     
  3305.     
  3306.     RETURN VALUE:
  3307.     
  3308.         The value of 'c', converted to upper case
  3309.     
  3310.     
  3311.     DESCRIPTION:
  3312.     
  3313.           Returns the value of 'c' converted to upper case. If 'c' is not  a
  3314.        letter of lower case, no change is made, and the  original  value  of
  3315.        'c' is returned.
  3316.     
  3317.     
  3318.     EXAMPLES:
  3319.     
  3320.         putc(toupper(output_char), stdout);
  3321.     WRITE                                                             WRITE
  3322.     
  3323.     
  3324.     
  3325.     PROTOTYPE:
  3326.     
  3327.         int write(char *block, int size, HANDLE fh)
  3328.     
  3329.     
  3330.     ARGUMENTS:
  3331.     
  3332.         block   - Pointer to a block of data to write
  3333.         size    - Number of bytes to write
  3334.         fh      - File handle of an output file
  3335.     
  3336.     
  3337.     RETURN VALUE:
  3338.     
  3339.         0 if successful, otherwise an operating system error code
  3340.     
  3341.     
  3342.     DESCRIPTION:
  3343.     
  3344.           This function writes a block of data to the indicated  file  using
  3345.        low level (unbuffered) I/O from memory at the specified address. Data
  3346.        is  written  in  "raw"  form,  with  no  translations  of   "newline"
  3347.        characters etc. If the value returned is less than the value  of  the
  3348.        "size" parameter, some error condition  has  occured  (Such  as  disk
  3349.        full).
  3350.     
  3351.     
  3352.     EXAMPLES:
  3353.     
  3354.         if(write(buffer, 100, fh) < 100)
  3355.             abort("File write error\n");
  3356.     MICRO-C Library                                                  Page: 3
  3357.  
  3358.  
  3359.     
  3360.                       +---------------------------------+
  3361.                       |                                 |
  3362.                       |  *****************************  |
  3363.                       |  * The IBM-PC/MS-DOS library *  |
  3364.                       |  *****************************  |
  3365.                       |                                 |
  3366.                       +---------------------------------+
  3367.     
  3368.     
  3369.     
  3370.     
  3371.     
  3372.     
  3373.     
  3374.     
  3375.     
  3376.     
  3377.        1.2 IBM-PC/MS-DOS Library
  3378.     
  3379.              The library functions described  on  the  following  pages  are
  3380.           available only under the MS-DOS operating  system,  on  IBM-PC  or
  3381.           compatible systems.
  3382.     
  3383.              These routines perform operations which are closely tied to the
  3384.           8086 family of processors, the  IBM-PC  hardware,  or  the  MS-DOS
  3385.           operating system, and are therefore impractical to implement on  a
  3386.           "general" basis.
  3387.     ALLOCA                                                           ALLOCA
  3388.     
  3389.     
  3390.     
  3391.     PROTOTYPE:
  3392.     
  3393.         char *alloca(int size)
  3394.     
  3395.     
  3396.     ARGUMENTS:
  3397.     
  3398.         size    - Size of memory block to allocate (in bytes).
  3399.     
  3400.     
  3401.     RETURN VALUE:
  3402.     
  3403.         0       - Memory allocation failed
  3404.         !0      - Pointer to allocated memory
  3405.     
  3406.     
  3407.     DESCRIPTION:
  3408.     
  3409.           The "alloca" function  allocates  a  block  of  automatic  (stack)
  3410.        memory, which exists only only until the  function  calling  "alloca"
  3411.        returns. When that function returns, all stack memory  including  any
  3412.        allocated by "alloca" is released.
  3413.     
  3414.        NOTE: THE FOLLOWING RESTRICTIONS APPLY TO THE USE OF ALLOCA:
  3415.     
  3416.           The function calling 'alloca' MUST have  at  least  one  automatic
  3417.        (local) variable, otherwise MICRO-C will not  restore  the  stack  on
  3418.        exit.
  3419.     
  3420.           The 'alloca' function must be used within a simple expression,  at
  3421.        a point where there will be no partial results stored on the stack.
  3422.     
  3423.           The above conditions can best be met by declaring a local  pointer
  3424.        which will hold the memory address, and assigning it the value of the
  3425.        'alloca' call in a single statement. The address returned by 'alloca'
  3426.        should NOT be assigned to a calculated  address  (such  as  an  array
  3427.        element or indirect reference via a pointer), since this  may  result
  3428.        in stack activity.
  3429.     
  3430.           NOTE: The size operand to 'alloca' can be  a  complex  expression,
  3431.        since any stack operations it causes will have dissipated by the time
  3432.        'alloca' gets called.
  3433.     
  3434.     
  3435.     EXAMPLES:
  3436.     
  3437.     func(string)
  3438.         char *string;
  3439.     {
  3440.         char *local_memory;
  3441.     
  3442.         if(!(local_memory = alloca(strlen(string)+1)))
  3443.             abort("Not enough memory for alloca");
  3444.         /* ... */
  3445.     }
  3446.     ALLOC_SEG                                                     ALLOC_SEG
  3447.     
  3448.     
  3449.     
  3450.     PROTOTYPE:
  3451.     
  3452.         int alloc_seg(int size)
  3453.     
  3454.     
  3455.     ARGUMENTS:
  3456.     
  3457.         size    - Number of 16 byte paragraphs to allocate
  3458.     
  3459.     
  3460.     RETURN VALUE:
  3461.     
  3462.     
  3463.         0       - Not enough free memory available
  3464.         !0      - The segment address of the allocated memory
  3465.     
  3466.     
  3467.     DESCRIPTION:
  3468.     
  3469.           The "alloc_seg" function allocates a 'segment' of memory from DOS.
  3470.        The size is given in 16 byte "paragraphs". The allocated memory  will
  3471.        be outside of the data memory available to the MICRO-C  program,  and
  3472.        therefore must be accessed via assembly lenguage functions,  or  with
  3473.        the "peek" and "poke" library functions.
  3474.     
  3475.     
  3476.     EXAMPLES:
  3477.     
  3478.         if(!(aseg = alloc(4096)))   /* Get a 64K data segment */
  3479.             abort("Not enough memory!!!");
  3480.         set_es(aseg);               /* Set up extra segment */
  3481.         asm_func();                 /* Invoke assembler function */
  3482.     BREAK                                                             BREAK
  3483.     
  3484.     
  3485.     
  3486.     PROTOTYPE:
  3487.     
  3488.         break(int allow)
  3489.     
  3490.     
  3491.     ARGUMENTS:
  3492.     
  3493.         allow   - 0 = disallow break, !0 = allow breaks
  3494.     
  3495.     
  3496.     RETURN VALUE:
  3497.     
  3498.         None
  3499.     
  3500.     
  3501.     DESCRIPTION:
  3502.     
  3503.           Controls the setting of the DOS "break" flag. When set  on  (allow
  3504.        != 0), the keyboard is tested for CONTROL-BREAK on any  DOS  function
  3505.        call. If set off (allow == 0), CONTROL-C is  only  recognized  during
  3506.        I/O to the keyboard and video display.
  3507.     
  3508.     
  3509.     EXAMPLES:
  3510.     
  3511.         break(1);   /* Disable keyboard interrupts */
  3512.     CCLOSE                                                           CCLOSE
  3513.     
  3514.     
  3515.     
  3516.     PROTOTYPE:
  3517.     
  3518.         Cclose()
  3519.     
  3520.     
  3521.     ARGUMENTS:
  3522.     
  3523.         None
  3524.     
  3525.     
  3526.     RETURN VALUE:
  3527.     
  3528.         None
  3529.     
  3530.     
  3531.     DESCRIPTION:
  3532.     
  3533.           This function closes the  communications  port  previously  opened
  3534.        using "Copen". The system interrupt vectors and all  other  hooks  to
  3535.        the comm port are restored.
  3536.     
  3537.           This function must be called  before  any  program  using  "Copen"
  3538.        terminates, otherwise the communications port  will  be  left  in  an
  3539.        indeterminate state. If this is not done, there will be a possibility
  3540.        of system crash if an interrupt is received from the port  after  the
  3541.        program has terminated.
  3542.     
  3543.     
  3544.     EXAMPLES:
  3545.     
  3546.         Cclose();       /* Close comm port */
  3547.         exit(0);        /* And terminate */
  3548.     CGETC                                                             CGETC
  3549.     
  3550.     
  3551.     
  3552.     PROTOTYPE:
  3553.     
  3554.         int Cgetc()
  3555.     
  3556.     
  3557.     ARGUMENTS:
  3558.     
  3559.         None
  3560.     
  3561.     
  3562.     RETURN VALUE:
  3563.     
  3564.         Character read from the communications port
  3565.     
  3566.     
  3567.     DESCRIPTION:
  3568.     
  3569.           This function reads a single  character  from  the  communications
  3570.        port previously opened with "Copen". If no  character  is  available,
  3571.        "Cgetc" will wait for one.
  3572.     
  3573.     
  3574.     EXAMPLES:
  3575.     
  3576.         /* Get a string from the comm port */
  3577.         while((c = cgetc()) != '\r')
  3578.             *ptr++ = c;
  3579.         *ptr = 0;
  3580.     COPEN                                                             COPEN
  3581.     
  3582.     
  3583.     
  3584.     PROTOTYPE:
  3585.     
  3586.         int Copen(int port, int speed, int mode, int modem)
  3587.     
  3588.     
  3589.     ARGUMENTS:
  3590.     
  3591.         port    - Comm port to use (1, 2, 3 or 4)
  3592.         speed   - Baudrate divisor to set
  3593.         mode    - Communications parameters to set
  3594.         modem   - Modem control lines to set
  3595.     
  3596.     RETURN VALUE:
  3597.     
  3598.         0       - Successful open
  3599.         !0      - Requested comm port is not available
  3600.     
  3601.     
  3602.     DESCRIPTION:
  3603.     
  3604.           The "Copen" function opens a serial communications port on the IBM
  3605.        PC for access. An independant interrupt handler and I/O  drivers  are
  3606.        installed, which allow high speed full duplex operation of the serial
  3607.        port with optional XON/XOFF flow control of both receive and transmit
  3608.        streams.
  3609.     
  3610.           Only one serial port  may  be  accessed  at  a  time  using  these
  3611.        functions, If "Copen" is called more than once, it will automatically
  3612.        close the last port before opening the new one.
  3613.     
  3614.           The meaning of the "speed",  "mode",  and  "modem"  parameters  if
  3615.        documented in the "comm.h" header file.
  3616.     
  3617.           An external "char" variable "Cflags" may be accessed to enable  or
  3618.        disable transparency of the serial  channel.  When  "transparent"  is
  3619.        selected, XON/XOFF flow control is disabled, and all data is sent and
  3620.        received with no changes. When  operating  in  this  mode,  you  must
  3621.        insure that "Cgetc" is called frequently enough  that  the  256  byte
  3622.        internal receive buffer will not overflow.
  3623.     
  3624.           Since "Cflags" is  used  by  the  interrupt  handler,  you  should
  3625.        disable and enable interrupts around any accesses to it.
  3626.     
  3627.     
  3628.     
  3629.     EXAMPLES:
  3630.     
  3631.         #include comm.h     /* Get comm port defintions */
  3632.     
  3633.             extern char Cflags;
  3634.     
  3635.         /*
  3636.          * Program to read & echo characters on the serial port
  3637.          * in transparent mode. (Until ESCAPE char is received)
  3638.          */
  3639.         main()
  3640.         {
  3641.             char c;
  3642.     
  3643.             if(Copen(1, _2400, PAR_NO|DATA_8|STOP_1, SET_RTS|SET_DTR))
  3644.                 abort("Cannot access COM1");
  3645.     
  3646.             disable();                  /* Disable interrupts */
  3647.             Cflags |= TRANSPARENT;      /* Set transparency */
  3648.             enable();                   /* Re-enable interrupts */
  3649.     
  3650.             while((c = Cgetc()) != 0x1B)    /* Do until ESCAPE */
  3651.                 Cputc(c);
  3652.     
  3653.             Cclose();                   /* Close the serial port */
  3654.         }
  3655.     COPY_SEG                                                       COPY_SEG
  3656.     
  3657.     
  3658.     
  3659.     PROTOTYPE:
  3660.     
  3661.         copy_seg(int dseg, int doffset, int sseg, int soffset, int size)
  3662.     
  3663.     
  3664.     ARGUMENTS:
  3665.     
  3666.         dseg    - Destination segment
  3667.         doffset - Destination offset
  3668.         sseg    - Source segment
  3669.         soffset - Source offset
  3670.         size    - Number of bytes to copy
  3671.     
  3672.     
  3673.     RETURN VALUE:
  3674.     
  3675.         None
  3676.     
  3677.     
  3678.     DESCRIPTION:
  3679.     
  3680.           This function  perform  a  copy  between  80X86  processor  memory
  3681.        segments. A number of bytes equal to "size" is copied from the source
  3682.        segment and offset to the destination segment and offset.
  3683.     
  3684.     
  3685.     EXAMPLES:
  3686.     
  3687.         /* Save the video display contents */
  3688.         copy_seg(get_ds(), buffer, _V_BASE, 0, (25*80)*2);
  3689.     CPU                                                                 CPU
  3690.     
  3691.     
  3692.     
  3693.     PROTOTYPE:
  3694.     
  3695.         int cpu()
  3696.     
  3697.     
  3698.     ARGUMENTS:
  3699.     
  3700.         None
  3701.     
  3702.     
  3703.     RETURN VALUE:
  3704.     
  3705.         0       - CPU is 8088 or 8086
  3706.         1       - CPU is 80188 or 80186
  3707.         2       - CPU is 80286
  3708.         3       - CPU is 80386 or 80486
  3709.     
  3710.     
  3711.     DESCRIPTION:
  3712.     
  3713.           This function  returns  a  simple  integer  which  identifies  the
  3714.        processor type on which the program is currently executing.
  3715.     
  3716.     
  3717.     EXAMPLES:
  3718.     
  3719.         if(cpu() < 2)
  3720.             abort("This program requires at least an 80286");
  3721.     CPUTC                                                             CPUTC
  3722.     
  3723.     
  3724.     
  3725.     PROTOTYPE:
  3726.     
  3727.         Cputc(char c)
  3728.     
  3729.     
  3730.     ARGUMENTS:
  3731.     
  3732.         c       - Character to write to communciation port
  3733.     
  3734.     
  3735.     RETURN VALUE:
  3736.     
  3737.         None
  3738.     
  3739.     
  3740.     DESCRIPTION:
  3741.     
  3742.           The  "Cputc"  function  writes  the   given   character   to   the
  3743.        communcinations port previously opened by "Copen".
  3744.     
  3745.     
  3746.     EXAMPLES:
  3747.     
  3748.         while(*ptr)         /* Write a string to comm port */
  3749.             Cputc(*ptr++);
  3750.     CSIGNALS                                                       CSIGNALS
  3751.     
  3752.     
  3753.     
  3754.     PROTOTYPE:
  3755.     
  3756.         int Csignals()
  3757.     
  3758.     
  3759.     ARGUMENTS:
  3760.     
  3761.         None
  3762.     
  3763.     
  3764.     RETURN VALUE:
  3765.     
  3766.         The modem input signals read from the open comm port
  3767.     
  3768.     
  3769.     DESCRIPTION:
  3770.     
  3771.           This function reads the modem input signals (DSR, CD, RI etc) from
  3772.        the serial communication  port  previously  opened  by  "Copen",  and
  3773.        returns them as an integer value.
  3774.     
  3775.           The meaning of the  individual  bits  in  the  value  returned  by
  3776.        "Csignals" is documented in the "comm.h" header file.
  3777.     
  3778.     
  3779.     EXAMPLES:
  3780.     
  3781.         if(!(Csignals() & DSR)) {
  3782.             Cclose();
  3783.             abort("Modem not ready"); }
  3784.     CTESTC                                                           CTESTC
  3785.     
  3786.     
  3787.     
  3788.     PROTOTYPE:
  3789.     
  3790.         int Ctestc()
  3791.     
  3792.     
  3793.     ARGUMENTS:
  3794.     
  3795.         None
  3796.     
  3797.     
  3798.     RETURN VALUE:
  3799.     
  3800.         0-255   - Character read from comm port
  3801.         -1      - No character available
  3802.     
  3803.     
  3804.     DESCRIPTION:
  3805.     
  3806.           This function tests for a character from the  communications  port
  3807.        previously opened with "Copen", and returns that character if one  if
  3808.        found. If no character is available, "Ctestc" returns -1.
  3809.     
  3810.     
  3811.     EXAMPLES:
  3812.     
  3813.         if((c = Ctestc()) == -1) {
  3814.             Cclose();
  3815.             abort("No character available"); }
  3816.     DELAY                                                             DELAY
  3817.     
  3818.     
  3819.     
  3820.     PROTOTYPE:
  3821.     
  3822.         delay(int msec)
  3823.     
  3824.     
  3825.     ARGUMENTS:
  3826.     
  3827.         msec    - Number of milliseconds to wait
  3828.     
  3829.     
  3830.     RETURN VALUE:
  3831.     
  3832.         None
  3833.     
  3834.     
  3835.     DESCRIPTION:
  3836.     
  3837.           Pauses for the specified number of milliseconds. This function  is
  3838.        limited to the accuracy of the BIOS clock,  which  operates  at  18.2
  3839.        ticks per second.
  3840.     
  3841.     
  3842.     EXAMPLES:
  3843.     
  3844.         delay(1000);        /* Wait one second */
  3845.     DISABLE                                                         DISABLE
  3846.     
  3847.     
  3848.     
  3849.     PROTOTYPE:
  3850.     
  3851.         disable()
  3852.     
  3853.     
  3854.     ARGUMENTS:
  3855.     
  3856.         None
  3857.     
  3858.     
  3859.     RETURN VALUE:
  3860.     
  3861.         None
  3862.     
  3863.     
  3864.     DESCRIPTION:
  3865.     
  3866.           The  "disable"  function  disables  the  8086  interrupt   system,
  3867.        preventing the  processor  from  servicing  interrupts.  It  is  used
  3868.        whenever the execution of an interrupt handler may interfere  with  a
  3869.        particular operation.
  3870.     
  3871.           When this function is used, the "enable" function should be called
  3872.        as soon as possible after "disable". Failure to do this may result in
  3873.        loss  of  system  functions  performed  under  interrupts,  such   as
  3874.        timekeeping, and serial communications (Via MICRO-C serial drivers).
  3875.     
  3876.     
  3877.     EXAMPLES:
  3878.     
  3879.         disable();                  /* Disallow interrupts */
  3880.         Cflags &= ~TRANSPARENT;     /* Remove transparency */
  3881.         enable();                   /* Re-allow interrupts */
  3882.     ENABLE                                                           ENABLE
  3883.     
  3884.     
  3885.     
  3886.     PROTOTYPE:
  3887.     
  3888.         enable()
  3889.     
  3890.     
  3891.     ARGUMENTS:
  3892.     
  3893.         None
  3894.     
  3895.     
  3896.     RETURN VALUE:
  3897.     
  3898.         None
  3899.     
  3900.     
  3901.     DESCRIPTION:
  3902.     
  3903.           The "enable" function enables the 8086 interrupt system,  allowing
  3904.        the processor to service interrupts. It should be called as  soon  as
  3905.        possible following the use of the "disable" function.
  3906.     
  3907.     
  3908.     EXAMPLES:
  3909.     
  3910.         disable();                  /* Disallow interrupts */
  3911.         Cflags |= TRANSPARENT;      /* Force  transparency */
  3912.         enable();                   /* Re-allow interrupts */
  3913.     EXEC                                                               EXEC
  3914.     
  3915.     
  3916.     
  3917.     PROTOTYPE:
  3918.     
  3919.         int exec(char *exefile, char *args)
  3920.     
  3921.     
  3922.     ARGUMENTS:
  3923.     
  3924.         exefile - Full pathname of a '.COM' or '.EXE' file
  3925.         args    - Command tail containing arguments
  3926.     
  3927.     
  3928.     RETURN VALUE:
  3929.     
  3930.         0 if successful, otherwise an MS-DOS error code
  3931.     
  3932.     
  3933.     DESCRIPTION:
  3934.     
  3935.           The "exec" function causes MS-DOS to suspend the execution of  the
  3936.        MICRO-C program, and then to execute the indicated '.EXE'  or  '.COM'
  3937.        program file. When that program terminates, execution of the  MICRO-C
  3938.        program will resume.
  3939.     
  3940.           This is a low level interface to the MS-DOS 'EXEC'  function,  and
  3941.        as such, it does not search your PATH, does not process '.BAT' files,
  3942.        nor provide any I/O redirection facilities. If you want to  make  use
  3943.        of these features (which are  provided  by  'COMMAND.COM'),  use  the
  3944.        higher level 'SYSTEM' function.
  3945.     
  3946.     
  3947.     EXAMPLES:
  3948.     
  3949.         printf("Type 'EXIT' to return to the MICRO-C program\n");
  3950.         exec("C:\\COMMAND.COM", "");    /* Start up a sub-shell */
  3951.     FREE_SEG                                                       FREE_SEG
  3952.     
  3953.     
  3954.     
  3955.     PROTOTYPE:
  3956.     
  3957.         int free_seg(int segment)
  3958.     
  3959.     
  3960.     ARGUMENTS:
  3961.     
  3962.         segment - A previously allocated segment of memory
  3963.     
  3964.     
  3965.     RETURN VALUE:
  3966.     
  3967.         0       - The segment was released
  3968.         !0      - DOS error code
  3969.     
  3970.     
  3971.     DESCRIPTION:
  3972.     
  3973.           The "free_seg" function releases a segment  of  memory  previously
  3974.        allocated by "alloc_seg", and returns it  to  the  operating  system.
  3975.        This should be used whenever your program has finished with a segment
  3976.        of extra memory which it has allocated.
  3977.     
  3978.     
  3979.     EXAMPLES:
  3980.     
  3981.         aseg = alloc_seg(4096);         /* Allocate a 64K segment */
  3982.         set_es(aseg);                   /* Set up extra segment */
  3983.         asm_func();                     /* Call assembler function */
  3984.         free_seg(aseg);                 /* Releas the memory */
  3985.     GET_ATTR                                                       GET_ATTR
  3986.     
  3987.     
  3988.     
  3989.     PROTOTYPE:
  3990.     
  3991.         int get_attr(char *pathname, int &attrs)
  3992.     
  3993.     
  3994.     ARGUMENTS:
  3995.     
  3996.         pathname- Name of file to get attributes of
  3997.         attrs   - Integer to receive attributes
  3998.     
  3999.     
  4000.     RETURN VALUE:
  4001.     
  4002.         0 if successful, otherwise an operating system error code
  4003.     
  4004.     
  4005.     DESCRIPTION:
  4006.     
  4007.           This function retreives the attributes of the specified file.
  4008.     
  4009.           The meaning of the individual bits in the "attrs" value is defined
  4010.        in the "file.h" header file.
  4011.     
  4012.     
  4013.     EXAMPLES:
  4014.     
  4015.         get_attr("tempfile", &attributes);
  4016.     GET_CS                                                           GET_CS
  4017.     
  4018.     
  4019.     
  4020.     PROTOTYPE:
  4021.     
  4022.         int get_cs()
  4023.     
  4024.     
  4025.     ARGUMENTS:
  4026.     
  4027.         None
  4028.     
  4029.     
  4030.     RETURN VALUE:
  4031.     
  4032.         The current processor CODE segment
  4033.     
  4034.     
  4035.     DESCRIPTION:
  4036.     
  4037.           This function is available only on the 8086 family of  processors,
  4038.        and returns the current processor CODE segment.
  4039.     
  4040.     
  4041.     EXAMPLES:
  4042.     
  4043.         code_seg = get_cs();
  4044.     GET_DATE                                                       GET_DATE
  4045.     
  4046.     
  4047.     
  4048.     PROTOTYPE:
  4049.     
  4050.         get_date(int &day, int &month, int &year)
  4051.     
  4052.     
  4053.     ARGUMENTS:
  4054.     
  4055.         &day    - Address of integer to receive day (1-31)
  4056.         &month  - Address of integer to receive month (1-12)
  4057.         &year   - Address of integer to receive year (1980-2099)
  4058.     
  4059.     
  4060.     RETURN VALUE:
  4061.     
  4062.         Day of week (0=Sun ... 6=Sat)
  4063.     
  4064.     
  4065.     DESCRIPTION:
  4066.     
  4067.           This function gets the current system  date  in  day,  month,  and
  4068.        year.
  4069.     
  4070.     
  4071.     EXAMPLES:
  4072.     
  4073.         get_date(&day, &month, &year);
  4074.         printf("%s %u, %u", months[month], day, year);
  4075.     GET_DRIVE                                                     GET_DRIVE
  4076.     
  4077.     
  4078.     
  4079.     PROTOTYPE:
  4080.     
  4081.         int get_drive()
  4082.     
  4083.     
  4084.     ARGUMENTS:
  4085.     
  4086.         None
  4087.     
  4088.     
  4089.     RETURN VALUE:
  4090.     
  4091.         The currently active (default) disk drive (0=A, 1=B, 2=C, ...)
  4092.     
  4093.     
  4094.     DESCRIPTION:
  4095.     
  4096.           The "get_drive" function returns the  drive  index  (0-n)  of  the
  4097.        currently active or "default" MS-DOS disk drive.
  4098.     
  4099.     
  4100.     EXAMPLES:
  4101.     
  4102.         old_drive = get_drive();
  4103.         set_drive(new_drive);
  4104.     GET_DS                                                           GET_DS
  4105.     
  4106.     
  4107.     
  4108.     PROTOTYPE:
  4109.     
  4110.         int get_ds()
  4111.     
  4112.     
  4113.     ARGUMENTS:
  4114.     
  4115.         None
  4116.     
  4117.     
  4118.     RETURN VALUE:
  4119.     
  4120.         The current processor DATA segment
  4121.     
  4122.     
  4123.     DESCRIPTION:
  4124.     
  4125.           This function is available only on the 8086 family of  processors,
  4126.        and returns the current processor DATA segment.
  4127.     
  4128.     
  4129.     EXAMPLES:
  4130.     
  4131.         data_seg = get_ds();
  4132.     GET_ES                                                           GET_ES
  4133.     
  4134.     
  4135.     
  4136.     PROTOTYPE:
  4137.     
  4138.         int get_es()
  4139.     
  4140.     
  4141.     ARGUMENTS:
  4142.     
  4143.         None
  4144.     
  4145.     
  4146.     RETURN VALUE:
  4147.     
  4148.         The current processor EXTRA segment
  4149.     
  4150.     
  4151.     DESCRIPTION:
  4152.     
  4153.           This function is available only on the 8086 family of  processors,
  4154.        and returns the current processor EXTRA segment.
  4155.     
  4156.     
  4157.     EXAMPLES:
  4158.     
  4159.         code_seg = get_es();
  4160.     GET_TIME                                                       GET_TIME
  4161.     
  4162.     
  4163.     
  4164.     PROTOTYPE:
  4165.     
  4166.         get_time(int &hour, int &minite, int &second)
  4167.     
  4168.     
  4169.     ARGUMENTS:
  4170.     
  4171.         &hour   - Address of integer to receive hour (0-23)
  4172.         &minite - Address of integer to receive minite (0-59)
  4173.         &second - Address of integer to receive second (0-59)
  4174.     
  4175.     
  4176.     RETURN VALUE:
  4177.     
  4178.         None
  4179.     
  4180.     
  4181.     DESCRIPTION:
  4182.     
  4183.           This function gets the current system time in hours,  minites  and
  4184.        seconds.
  4185.     
  4186.     
  4187.     EXAMPLES:
  4188.     
  4189.         get_time(&hour, &minite, &second);
  4190.         printf("%02:%02:%02", hour, minite, second);
  4191.     INT86                                                             INT86
  4192.     
  4193.     
  4194.     
  4195.     PROTOTYPE:
  4196.     
  4197.         int int86(int inum)
  4198.     
  4199.     
  4200.     ARGUMENTS:
  4201.     
  4202.         inum    - The 8086 software interrupt to execute
  4203.     
  4204.     
  4205.     RETURN VALUE:
  4206.     
  4207.         8086 FLAGS register after interrupt executes.
  4208.     
  4209.     
  4210.     DESCRIPTION:
  4211.     
  4212.           This  function  performs  an  8086  software   interrupt.   Before
  4213.        executing the interrupt, the processor registers are loaded from  the
  4214.        external "int" variables: _AX_, _BX_, _CX_, _DX_, _SI_ and _DI_.  The
  4215.        DS, ES and SS segment registers are all set  to  point  to  MICRO-C's
  4216.        data segment.
  4217.     
  4218.           After the interrupt  completes,  the  contents  of  the  processor
  4219.        registers are copied to the above named variables.
  4220.     
  4221.     
  4222.     EXAMPLES:
  4223.     
  4224.         extern int _AX_, _DX_;
  4225.         main() {
  4226.             _AX_ = 0x0200;  /* MSDOS function 2 - Output character */
  4227.             _DX_ = '$';     /* Character to output */
  4228.             int86(0x21);    /* Call MSDOS */
  4229.         }
  4230.     RESIZE_SEG                                                   RESIZE_SEG
  4231.     
  4232.     
  4233.     
  4234.     PROTOTYPE:
  4235.     
  4236.         int resize_seg(int segment, int size)
  4237.     
  4238.     
  4239.     ARGUMENTS:
  4240.     
  4241.         segment - A previously allocated segment of memory
  4242.         size    - Desired size (in 16 byte paragraphs)
  4243.     
  4244.     
  4245.     RETURN VALUE:
  4246.     
  4247.         0       - The segments size has been adjusted
  4248.         !0      - DOS error code
  4249.     
  4250.     
  4251.     DESCRIPTION:
  4252.     
  4253.           The "resize_seg" function provides a method of changing  the  size
  4254.        of a segment of memory previously allocated via "alloc_seg".  If  not
  4255.        enough memory is available, the function will fail  with  a  ono-zero
  4256.        return value.
  4257.     
  4258.           This function may also be used to adjust the memoey allocation  of
  4259.        the programs image, by passing it the segment address of the programs
  4260.        own PSP. This value is available in the external variable "PSP".
  4261.     
  4262.           MICRO-C normally allocates 64K for programs compiled in  the  TINY
  4263.        model, and (64K + (256 byte PSP) + (size  of  executable  code))  for
  4264.        programs compiled in the SMALL model. This allocation should NEVER be
  4265.        reduced, however you may enlarge it if your program wishes to  access
  4266.        additional data immediately following its own DATA/STACK segment.
  4267.     
  4268.     
  4269.     EXAMPLES:
  4270.     
  4271.         extern int PSP;
  4272.     
  4273.         main()
  4274.         {
  4275.             if(resize_seg(PSP, 8192))   /* Append 64K buffer */
  4276.                 abort("Not enough memory!!!");
  4277.             ...     /* Remainder of program */
  4278.         }
  4279.     RESTORE_VIDEO                                             RESTORE_VIDEO
  4280.     
  4281.     
  4282.     
  4283.     PROTOTYPE:
  4284.     
  4285.         restore_video(char buffer[4006]);
  4286.     
  4287.     
  4288.     ARGUMENTS:
  4289.     
  4290.         buffer  - Video save area.
  4291.     
  4292.     
  4293.     RETURN VALUE:
  4294.     
  4295.         None
  4296.     
  4297.     
  4298.     DESCRIPTION:
  4299.     
  4300.           The RESTORE_VIDEO function restores the contents and state of  the
  4301.        IBM P.C. video display to the state it was in when  "SAVE_VIDEO"  was
  4302.        executed. At the present time, the function  is  effective  only  for
  4303.        text modes. Graphics screens will not be restored, due  to  the  high
  4304.        memory requirements.
  4305.     
  4306.           Although this function is useful in ANY program  (to  restore  the
  4307.        DOS screen before termination), it is most  useful  in  "POP-UP"  ram
  4308.        resident programs (See "TSR" function), to save  the  screen  of  any
  4309.        application which may be running when you pop up.
  4310.     
  4311.           The video state is restored from  the  passed  "buffer"  argument,
  4312.        which is 4006 bytes  in  size,  and  must  have  been  filled  in  by
  4313.        "SAVE_VIDEO". It has the following format:
  4314.     
  4315.                   buffer[0]         - Video mode
  4316.                     "   [1]         - Video page
  4317.                     "   [2]         - 'X' cursor position
  4318.                     "   [3]         - 'Y' cursor position
  4319.                     "   [4]         - Ending line for cursor
  4320.                     "   [5]         - Starting line for cursor
  4321.                     "   [6-4005]    - Saved video screen contents
  4322.     
  4323.     
  4324.     EXAMPLES:
  4325.     
  4326.         popup_func()
  4327.         {
  4328.             save_video();
  4329.             perform_function();
  4330.             restore_video();
  4331.         }
  4332.     SAVE_VIDEO                                                   SAVE_VIDEO
  4333.     
  4334.     
  4335.     
  4336.     PROTOTYPE:
  4337.     
  4338.         save_video(char buffer[4006]);
  4339.     
  4340.     
  4341.     ARGUMENTS:
  4342.     
  4343.         buffer  - Video save area.
  4344.     
  4345.     
  4346.     RETURN VALUE:
  4347.     
  4348.         None
  4349.     
  4350.     
  4351.     DESCRIPTION:
  4352.     
  4353.           The SAVE_VIDEO function saves the current contents  and  state  of
  4354.        the IBM P.C. video display. The screen may be restored  at  any  time
  4355.        using "RESTORE_VIDEO". At the present time, the function is effective
  4356.        only for text modes. Graphics screens will not be saved, due  to  the
  4357.        high memory requirements.
  4358.     
  4359.           Although this function is useful in ANY program  (to  restore  the
  4360.        DOS screen before termination), it is most  useful  in  "POP-UP"  ram
  4361.        resident programs (See "TSR" function), to save  the  screen  of  any
  4362.        application which may be running when you pop up.
  4363.     
  4364.           The video state is saved in the passed "buffer" argument, which is
  4365.        4006 bytes in size, and has the following format:
  4366.     
  4367.                   buffer[0]         - Video mode
  4368.                     "   [1]         - Video page
  4369.                     "   [2]         - 'X' cursor position
  4370.                     "   [3]         - 'Y' cursor position
  4371.                     "   [4]         - Ending line for cursor
  4372.                     "   [5]         - Starting line for cursor
  4373.                     "   [6-4005]    - Saved video screen contents
  4374.     
  4375.     
  4376.     EXAMPLES:
  4377.     
  4378.         popup_func()
  4379.         {
  4380.             save_video();
  4381.             perform_function();
  4382.             restore_video();
  4383.         }
  4384.     SET_ATTR                                                       SET_ATTR
  4385.     
  4386.     
  4387.     
  4388.     PROTOTYPE:
  4389.     
  4390.         int set_attr(char *pathname, int attrs)
  4391.     
  4392.     
  4393.     ARGUMENTS:
  4394.     
  4395.         pathname- Name of file to get attributes of
  4396.         attrs   - New attributes
  4397.     
  4398.     
  4399.     RETURN VALUE:
  4400.     
  4401.         0 if successful, otherwise an operating system error code
  4402.     
  4403.     
  4404.     DESCRIPTION:
  4405.     
  4406.           This function sets the system attributes of the specified file.
  4407.     
  4408.           The meaning of the individual bits in the "attrs" value is defined
  4409.        in the "file.h" header file.
  4410.     
  4411.     
  4412.     EXAMPLES:
  4413.     
  4414.         set_attr("tempfile", READONLY|HIDDEN);
  4415.     SET_DATE                                                       SET_DATE
  4416.     
  4417.     
  4418.     
  4419.     PROTOTYPE:
  4420.     
  4421.         set_date(int day, int month, int year)
  4422.     
  4423.     
  4424.     ARGUMENTS:
  4425.     
  4426.         day     - New day (1-31)
  4427.         month   - New month (1-12)
  4428.         year    - New year (1980-2099)
  4429.     
  4430.     
  4431.     RETURN VALUE:
  4432.     
  4433.         0       - Success
  4434.         -1      - Invalid date given
  4435.     
  4436.     
  4437.     DESCRIPTION:
  4438.     
  4439.           This function sets the current system  date  to  day,  month,  and
  4440.        year.
  4441.     
  4442.     
  4443.     EXAMPLES:
  4444.     
  4445.         set_date(1, 1, 1980);   /* Set to Jan 1, 1980 */
  4446.     SET_DRIVE                                                     SET_DRIVE
  4447.     
  4448.     
  4449.     
  4450.     PROTOTYPE:
  4451.     
  4452.         int set_drive(int drive)
  4453.     
  4454.     
  4455.     ARGUMENTS:
  4456.     
  4457.         Drive   - New drive index (0=A, 1=B, 2=C ...)
  4458.     
  4459.     
  4460.     RETURN VALUE:
  4461.     
  4462.         The total number of "logical" disk drives in the system
  4463.     
  4464.     
  4465.     DESCRIPTION:
  4466.     
  4467.           The "set_drive" function sets the  disk  drive  indicated  by  the
  4468.        "drive" index (0-x) to be the currently active  or  "default"  MS-DOS
  4469.        disk drive.
  4470.     
  4471.     
  4472.     EXAMPLES:
  4473.     
  4474.         old_drive = get_drive();
  4475.         set_drive(new_drive);
  4476.     SET_ES                                                           SET_ES
  4477.     
  4478.     
  4479.     
  4480.     PROTOTYPE:
  4481.     
  4482.         int set_es(int segment)
  4483.     
  4484.     
  4485.     ARGUMENTS:
  4486.     
  4487.         segment - The 16 bit new segment value
  4488.     
  4489.     
  4490.     RETURN VALUE:
  4491.     
  4492.         None
  4493.     
  4494.     
  4495.     DESCRIPTION:
  4496.     
  4497.           This function is available only on the 8086 family of  processors,
  4498.        and sets the processors EXTRA segment to the indicated value.
  4499.     
  4500.     
  4501.     EXAMPLES:
  4502.     
  4503.         set_es(get_ds());       /* Copy DATA to EXTRA segments */
  4504.     SET_TIME                                                       SET_TIME
  4505.     
  4506.     
  4507.     
  4508.     PROTOTYPE:
  4509.     
  4510.         set_time(int hour, int minite, int second)
  4511.     
  4512.     
  4513.     ARGUMENTS:
  4514.     
  4515.         hour    - New hour (0-23)
  4516.         minite  - New minite (0-59)
  4517.         second  - New second (0-59)
  4518.     
  4519.     
  4520.     RETURN VALUE:
  4521.     
  4522.         0       - Success
  4523.         -1      - Invalid time given
  4524.     
  4525.     
  4526.     DESCRIPTION:
  4527.     
  4528.           This function sets the current system time to "hour", "minite" and
  4529.        "second".
  4530.     
  4531.     
  4532.     EXAMPLES:
  4533.     
  4534.         set_time(0, 0, 0);  /* Set to 00:00:00 (midnight) */
  4535.     TSR                                                                 TSR
  4536.     
  4537.     
  4538.     
  4539.     PROTOTYPE:
  4540.     
  4541.         tsr(&func, int hotkey, int alloc)
  4542.     
  4543.     
  4544.     ARGUMENTS:
  4545.     
  4546.         func    - Address of function to execute
  4547.         hotkey  - POP-UP activation hotkeys
  4548.         alloc   - Memory allocation
  4549.     
  4550.     
  4551.     RETURN VALUE:
  4552.     
  4553.         Function normally never returns, but if it does, an
  4554.         operating system error code is passed back.
  4555.     
  4556.     
  4557.     DESCRIPTION:
  4558.     
  4559.           The TSR function terminates the MICRO-C  program,  but  leaves  it
  4560.        resident in memory. When the specified "HOT KEYS" are detected on the
  4561.        IBM PC keyboard, the context of whatever program is running is saved,
  4562.        and the specified MICRO-C function  is  called.  When  that  function
  4563.        returns, the interrupted program is resumed.
  4564.     
  4565.           When activated this way, THE "func" FUNCTION  MUST  NOT  TERMINATE
  4566.        WITH "exit" or one of its related functions (abort  etc.).  THE  ONLY
  4567.        WAY IT MAY TERMINATE IS TO "return" NORMALLY.
  4568.     
  4569.           The meaning of "hotkey" is defined in the "tsr.h" header file.
  4570.     
  4571.           The "alloc" paremeter specifies how much extra  memory  is  to  be
  4572.        retained in the TSR image for use  by  the  MICRO-C  stack  and  heap
  4573.        memory allocation functions. The "func" function(s) must insure  that
  4574.        the total amount of memory used by the stack and  calls  to  "malloc"
  4575.        does not exceed this value.
  4576.     
  4577.           NOTE: "malloc" will fail if the heap grows to  within  1K  of  the
  4578.        stack pointer.
  4579.     
  4580.           All memory used by  code,  global  variables,  string  space,  and
  4581.        "malloc" calls prior to the use of "tsr" is  automatically  retained,
  4582.        and should not be included in the "alloc" value.
  4583.     
  4584.           TSR programs which perform screen I/O should take care to save and
  4585.        restore the screen contents when popping up and down.
  4586.     
  4587.     
  4588.     EXAMPLES:
  4589.     
  4590.         tsr(&popup_func, ALT+L_SHIFT, 1024);
  4591.     VCLEAR_BOX                                                   VCLEAR_BOX
  4592.     
  4593.     
  4594.     
  4595.     PROTOTYPE:
  4596.     
  4597.         vclear_box(int x, int y, int w, int h)
  4598.     
  4599.     
  4600.     ARGUMENTS:
  4601.     
  4602.         x       - COLUMN of top left corner of box
  4603.         y       - ROW of top left corner of box
  4604.         w       - Width of box (columns)
  4605.         h       - Height of box (rows)
  4606.     
  4607.     
  4608.     RETURN VALUE:
  4609.     
  4610.         None
  4611.     
  4612.     
  4613.     DESCRIPTION:
  4614.     
  4615.           This function clears a box of the specified height and  width,  at
  4616.        the indicated 'X' and 'Y' coordinates, on  the  IBM-PC  video  screen
  4617.        using the block graphics characters. The entire  box  is  cleared  to
  4618.        spaces.
  4619.     
  4620.           "VOPEN" MUST be called prior to using this function.
  4621.     
  4622.     
  4623.     EXAMPLES:
  4624.     
  4625.         vclear_box(21, 11, 8, 3);   /* Clear a BOX */
  4626.     VCLEOL                                                           VCLEOL
  4627.     
  4628.     
  4629.     
  4630.     PROTOTYPE:
  4631.     
  4632.         vcleol()
  4633.     
  4634.     
  4635.     ARGUMENTS:
  4636.     
  4637.         None
  4638.     
  4639.     
  4640.     RETURN VALUE:
  4641.     
  4642.         None
  4643.     
  4644.     
  4645.     DESCRIPTION:
  4646.     
  4647.           This function clears the IBM PC  video  screen  from  the  current
  4648.        cursor position to the end of a line.
  4649.     
  4650.           You must "#include video.h", and execute "VOPEN"  prior  to  using
  4651.        this function.
  4652.     
  4653.     
  4654.     EXAMPLES:
  4655.     
  4656.         vprintf("Input> ");     /* Display a prompt */
  4657.         vcleol();               /* Clear remainder of input line */
  4658.     VCLEOS                                                           VCLEOS
  4659.     
  4660.     
  4661.     
  4662.     PROTOTYPE:
  4663.     
  4664.         vcleos()
  4665.     
  4666.     
  4667.     ARGUMENTS:
  4668.     
  4669.         None
  4670.     
  4671.     
  4672.     RETURN VALUE:
  4673.     
  4674.         None
  4675.     
  4676.     
  4677.     DESCRIPTION:
  4678.     
  4679.           This function clears the IBM PC  video  screen  from  the  current
  4680.        cursor position to the end of a screen.
  4681.     
  4682.           "VOPEN" MUST be called prior to using this function.
  4683.     
  4684.     
  4685.     EXAMPLES:
  4686.     
  4687.         vgotoxy(0, 10);         /* position at line 11 */
  4688.         vcleos();               /* Clear lower part of screen */
  4689.     VCLSCR                                                           VCLSCR
  4690.     
  4691.     
  4692.     
  4693.     PROTOTYPE:
  4694.     
  4695.         vclscr()
  4696.     
  4697.     
  4698.     ARGUMENTS:
  4699.     
  4700.         None
  4701.     
  4702.     
  4703.     RETURN VALUE:
  4704.     
  4705.         None
  4706.     
  4707.     
  4708.     DESCRIPTION:
  4709.     
  4710.           This function clears the entire IBM PC video screen and resets the
  4711.        cursor position to the top left hand corner.
  4712.     
  4713.           "VOPEN" MUST be called prior to using this function.
  4714.     
  4715.     
  4716.     EXAMPLES:
  4717.     
  4718.         if(c = 0x1b) {          /* Escape command */
  4719.             vclscr();       /* Clear the screen */
  4720.             vprintf("%s has terminated\n", argv[0]);
  4721.             exit(-1); }
  4722.     VCURSOR_BLOCK                                             VCURSOR_BLOCK
  4723.     
  4724.     
  4725.     
  4726.     PROTOTYPE:
  4727.     
  4728.         vcursor_block()
  4729.     
  4730.     
  4731.     ARGUMENTS:
  4732.     
  4733.         None
  4734.     
  4735.     
  4736.     RETURN VALUE:
  4737.     
  4738.         None
  4739.     
  4740.     
  4741.     DESCRIPTION:
  4742.     
  4743.           This function enables (turns on) display of the cursor on the  IBM
  4744.        PC video display. The cursor is shown as  flashing  block,  occupying
  4745.        the entire character window.
  4746.     
  4747.           "VOPEN" MUST be called prior to using this function.
  4748.     
  4749.     
  4750.     EXAMPLES:
  4751.     
  4752.         if(insert)              /* Test insert mode flag */
  4753.             vcursor_block();    /* Indicate inserting with block cursor */
  4754.         else
  4755.             vcursor_line();     /* Indicate overwrite with line cursor */
  4756.     VCURSOR_LINE                                               VCURSOR_LINE
  4757.     
  4758.     
  4759.     
  4760.     PROTOTYPE:
  4761.     
  4762.         vcursor_line()
  4763.     
  4764.     
  4765.     ARGUMENTS:
  4766.     
  4767.         None
  4768.     
  4769.     
  4770.     RETURN VALUE:
  4771.     
  4772.         None
  4773.     
  4774.     
  4775.     DESCRIPTION:
  4776.     
  4777.           This function enables (turns on) display of the cursor on the  IBM
  4778.        PC video display. The cursor is shown as a single flashing  line,  at
  4779.        the bottom of the character window.
  4780.     
  4781.           "VOPEN" MUST be called prior to using this function.
  4782.     
  4783.     
  4784.     EXAMPLES:
  4785.     
  4786.         vcursor_line();     /* Re-enable the cursor */
  4787.         exit(0);            /* And terminate */
  4788.     VCURSOR_OFF                                                 VCURSOR_OFF
  4789.     
  4790.     
  4791.     
  4792.     PROTOTYPE:
  4793.     
  4794.         vcursor_off()
  4795.     
  4796.     
  4797.     ARGUMENTS:
  4798.     
  4799.         None
  4800.     
  4801.     
  4802.     RETURN VALUE:
  4803.     
  4804.         None
  4805.     
  4806.     
  4807.     DESCRIPTION:
  4808.     
  4809.           This function inhibits (turns off) display of the  cursor  on  the
  4810.        IBM PC video display. This affects the cursor  display  only,  screen
  4811.        output will continue to be displayed at the correct cursor position.
  4812.     
  4813.           "VOPEN" MUST be called prior to using this function.
  4814.     
  4815.     
  4816.     EXAMPLES:
  4817.     
  4818.         vclscr();           /* Clear screen */
  4819.         vcursor_off();      /* Inhibit cursor */
  4820.         vmenu(10, 10, main_menu, 0, &index);    /* Present main menu */
  4821.     VDRAW_BOX                                                     VDRAW_BOX
  4822.     
  4823.     
  4824.     
  4825.     PROTOTYPE:
  4826.     
  4827.         vdraw_box(int x, int y, int w, int h)
  4828.     
  4829.     
  4830.     ARGUMENTS:
  4831.     
  4832.         x       - COLUMN of top left corner of box
  4833.         y       - ROW of top left corner of box
  4834.         w       - Width of box (columns)
  4835.         h       - Height of box (rows)
  4836.     
  4837.     
  4838.     RETURN VALUE:
  4839.     
  4840.         None
  4841.     
  4842.     
  4843.     DESCRIPTION:
  4844.     
  4845.           This function draws a box of the specified height  and  width,  at
  4846.        the indicated 'X' and 'Y' coordinates, on  the  IBM-PC  video  screen
  4847.        using the block graphics characters.
  4848.     
  4849.           "VOPEN" MUST be called prior to using this function.
  4850.     
  4851.     
  4852.     EXAMPLES:
  4853.     
  4854.         vdraw_box(20, 10, 10, 5);   /* Draw a BOX */
  4855.     VERSION                                                         VERSION
  4856.     
  4857.     
  4858.     
  4859.     PROTOTYPE:
  4860.     
  4861.         int version()
  4862.     
  4863.     
  4864.     ARGUMENTS:
  4865.     
  4866.         None
  4867.     
  4868.     
  4869.     RETURN VALUE:
  4870.     
  4871.         MS-DOS operating system version number
  4872.     
  4873.     
  4874.     DESCRIPTION:
  4875.     
  4876.           The "version" function is available only under MS-DOS, and returns
  4877.        the version number of the operating system.
  4878.     
  4879.           The higher 8 bits  of  the  returned  value  indicates  the  MAJOR
  4880.        version number ('3' in DOS 3.1)
  4881.     
  4882.           The lower 8 bits of the returned value indicates the MINOR version
  4883.        nuber ('1' in DOS 3.1).
  4884.     
  4885.     
  4886.     EXAMPLES:
  4887.     
  4888.         if(version() < 0x031E)
  4889.             abort("Requires DOS 3.30 or higher\n");
  4890.     VGETC                                                             VGETC
  4891.     
  4892.     
  4893.     
  4894.     PROTOTYPE:
  4895.     
  4896.         int vgetc()
  4897.     
  4898.     
  4899.     ARGUMENTS:
  4900.     
  4901.         None
  4902.     
  4903.     
  4904.     RETURN VALUE:
  4905.     
  4906.         0-127   - ASCII value of key pressed
  4907.         < 0     - Special function key as defined in "video.h"
  4908.     
  4909.     
  4910.     DESCRIPTION:
  4911.     
  4912.           The "vgetc" function waits until a key is pressed  on  the  system
  4913.        console, and returns its value.
  4914.     
  4915.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  4916.        keypress will be reported, even if the VGETC function is called after
  4917.        a key is pressed and released.
  4918.     
  4919.     
  4920.     EXAMPLES:
  4921.     
  4922.         switch(vgetc()) {       /* Handle input keys
  4923.                 . . .
  4924.         }
  4925.     VGETS                                                             VGETS
  4926.     
  4927.     
  4928.     
  4929.     PROTOTYPE:
  4930.     
  4931.         int vgets(int x, int y, char *prompt, char *field, int width)
  4932.     
  4933.     
  4934.     ARGUMENTS:
  4935.     
  4936.         x       - COLUMN of top left corner of input box
  4937.         y       - ROW of top left corner of input box
  4938.         prompt  - String to prompt with
  4939.         field   - String to receive the data
  4940.         width   - Width in characters of input field
  4941.     
  4942.     
  4943.     RETURN VALUE:
  4944.     
  4945.         0   - Selection was made and ENTER pressed.
  4946.         !0  - Input was aborted via ESCAPE key.
  4947.     
  4948.     
  4949.     DESCRIPTION:
  4950.     
  4951.           The "vgets" function draws a  box  on  the  video  screen  at  the
  4952.        specified X and Y coordinates, then prompts for and receives an input
  4953.        string in the box. The box is  drawn  large  enough  to  contain  the
  4954.        prompt and  the  specified  width  of  input  field.  The  prompt  is
  4955.        displayed at the left hand  side  of  the  box,  and  the  cursor  is
  4956.        positioned immediatly following it, at the start of the input field.
  4957.     
  4958.           The "field" parameter is the  address  of  a  character  array  to
  4959.        receive the input string. The previous value of the "field" array  is
  4960.        inserted into the input box when VGETS is invoked. If you do not want
  4961.        to display an old value, you should set the first  character  pointed
  4962.        to by field to zero, before calling VGETS.
  4963.     
  4964.           When entering the string, the user may use the  following  special
  4965.        keys to edit the input field:
  4966.     
  4967.                 Right Arrow - Move forward one character
  4968.                 Left  Arrow - Move backward one character
  4969.                 Delete      - Delete the character under the cursor
  4970.                 Backspace   - Move backward one character and delete.
  4971.                 Home        - Move to beginning of string
  4972.                 End         - Move to end of string
  4973.                 PgUp        - Clear (erase) entire string
  4974.                 PgDn        - Clear from cursor to end of string
  4975.                 Enter       - Accept (enter) the string
  4976.                 ESC         - Abort the input request
  4977.     
  4978.           All data entered in the input box is inserted into any data  which
  4979.        is already present.
  4980.     
  4981.     
  4982.     
  4983.     EXAMPLES:
  4984.     
  4985.         name[0] = 0;
  4986.         if(vgets(10, 10, "Your name?", name, 30))
  4987.             return;     /* Aborted, exit to higher level */
  4988.     VGOTOXY                                                         VGOTOXY
  4989.     
  4990.     
  4991.     
  4992.     PROTOTYPE:
  4993.     
  4994.         vgotoxy(int x, int y)
  4995.     
  4996.     
  4997.     ARGUMENTS:
  4998.     
  4999.         x       - New COLUMN (0-79)
  5000.         y       - New ROW    (0-24)
  5001.     
  5002.     
  5003.     RETURN VALUE:
  5004.     
  5005.         None
  5006.     
  5007.     
  5008.     DESCRIPTION:
  5009.     
  5010.           The "vgotoxy" function positions the cursor on  the  IBM-PC  video
  5011.        screen. Any further display output will occur  at  the  new  ROW  and
  5012.        COLUMN on the screen.
  5013.     
  5014.           The extern "int" variable "V_XY" may be referenced to read or  set
  5015.        the  current  X/Y  position.  The  higher  8  bits  contain  the  'Y'
  5016.        coordinate, and the lower 8 bits contain the 'X' coordinate. If  this
  5017.        variable is used to set (restore) the  cursor  position,  "vupdatexy"
  5018.        must then be called to position the physical cursor.
  5019.     
  5020.           "VOPEN" MUST be called prior to using this function.
  5021.     
  5022.     
  5023.     EXAMPLES:
  5024.     
  5025.         for(i=0; i<24; ++i) {   /* Draw a diagonal line of 'X's */
  5026.             vgotoxy(i, i);
  5027.             vputc('X'); }
  5028.     VMENU                                                             VMENU
  5029.     
  5030.     
  5031.     
  5032.     PROTOTYPE:
  5033.     
  5034.         vmenu(int x, int y, char *names[], char erase, int &index)
  5035.     
  5036.     
  5037.     ARGUMENTS:
  5038.     
  5039.         x       - COLUMN of top left corner of menu box
  5040.         y       - ROW of top left corner of menu box
  5041.         names   - Array to menu selection text (last entry = 0)
  5042.         erase   - 1=Erase BOX after selection is made
  5043.         index   - Address of message selection index variable
  5044.     
  5045.     
  5046.     RETURN VALUE:
  5047.     
  5048.         0   - Selection was made and ENTER pressed.
  5049.         !0  - Menu was aborted via ESCAPE key.
  5050.     
  5051.     
  5052.     DESCRIPTION:
  5053.     
  5054.           The "vmenu" function displays a list of menu items enclosed  in  a
  5055.        box on the IBM-PC video  screen  at  the  specified  ROW  and  COLUMN
  5056.        address. The user may use the UP, DOWN, HOME and END keys  to  select
  5057.        an entry by moving the INVERSE VIDEO selection cursor.
  5058.     
  5059.           When the desired selection is under the cursor, the  selection  is
  5060.        made by pressing the ENTER key.
  5061.     
  5062.           At any time the menu selection may be  canceled  by  pressing  the
  5063.        ESCAPE key.
  5064.     
  5065.           The "names" argument must be a pointer to an  array  of  character
  5066.        strings which are the selections to display. This array MUST end with
  5067.        a zero (0) element to indicate the end of the list.
  5068.     
  5069.           The "erase" flag indicates that the menu box should be cleared  to
  5070.        blanks when the selection is made. If "erase=0", the menu box is left
  5071.        on the screen, WITHOUT the selection cursor, with the selected  entry
  5072.        marked by '>' and '<'. The menu box is always erased when the menu is
  5073.        aborted with the ESCAPE key.
  5074.     
  5075.           The "index" argument is the address of  an  "int"  variable  which
  5076.        contains the position of the selection cursor. It controls where  the
  5077.        selection cursor will appear when the function is first invoked (0  =
  5078.        first entry), and also is assigned  the  position  of  the  selection
  5079.        cursor when the selection is made.
  5080.     
  5081.     
  5082.     
  5083.     EXAMPLES:
  5084.     
  5085.         char *names[] = { "One", "Two", "Three", "Four", "Five", 0 };
  5086.             . . .
  5087.         index = 0;
  5088.         if(vmenu(10, 10, names, 0, &index))
  5089.             return;         /* Aborted, exit to higher level */
  5090.         switch(index) {     /* Handle selection */
  5091.             . . .
  5092.         }
  5093.     VMESSAGE                                                       VMESSAGE
  5094.     
  5095.     
  5096.     
  5097.     PROTOTYPE:
  5098.     
  5099.         vmessage(int x, int y, char *string)
  5100.     
  5101.     
  5102.     ARGUMENTS:
  5103.     
  5104.         x       - COLUMN of top left corner of message box
  5105.         y       - ROW of top left corner of message box
  5106.         string  - Message to display
  5107.     
  5108.     
  5109.     RETURN VALUE:
  5110.     
  5111.         None
  5112.     
  5113.     
  5114.     DESCRIPTION:
  5115.     
  5116.           The "vmessage" function displays a text  string  surrounded  by  a
  5117.        BOX, on the IBM-PC video screen, at  the  specified  ROW  and  COLUMN
  5118.        address.
  5119.     
  5120.           "VOPEN" MUST be called prior to using this function.
  5121.     
  5122.     
  5123.     EXAMPLES:
  5124.     
  5125.         vmessage(20, 20, "Press any KEY to continue");
  5126.         get_key();
  5127.         vclear_box(20, 20, 26, 2);
  5128.     VOPEN                                                             VOPEN
  5129.     
  5130.     
  5131.     
  5132.     PROTOTYPE:
  5133.     
  5134.         vopen()
  5135.     
  5136.     
  5137.     ARGUMENTS:
  5138.     
  5139.         None
  5140.     
  5141.     
  5142.     RETURN VALUE:
  5143.     
  5144.         None
  5145.     
  5146.     
  5147.     DESCRIPTION:
  5148.     
  5149.           This function initializes the IBM-PC video display adapter for use
  5150.        with the MICRO-C video library functions. It determines  the  adapter
  5151.        type  (COLOR  ot  MONOCHROME),  sets  up  internal   variables   with
  5152.        information required by the other video  functions,  and  clears  the
  5153.        video screen.
  5154.     
  5155.           This function MUST  be  called  before  any  of  the  other  video
  5156.        functions in the library are used.
  5157.     
  5158.           After "vopen" is called, the extern "int" variable "V_BASE" may be
  5159.        referenced to determine the memory segment of the video display (B000
  5160.        for monochrome, B800 for color).
  5161.     
  5162.           Any program using the video library  functions  must  include  the
  5163.        "video.h" header file.
  5164.     
  5165.     
  5166.     EXAMPLES:
  5167.     
  5168.         vopen();
  5169.     VPRINTF                                                         VPRINTF
  5170.     
  5171.     
  5172.     
  5173.     PROTOTYPE:
  5174.     
  5175.         register vprintf(char *format, arg, ...)
  5176.     
  5177.     
  5178.     ARGUMENTS:
  5179.     
  5180.         format  - Pointer to format string
  5181.         arg     - Argument as determined by format string
  5182.         ...     - Additional arguments may be required
  5183.     
  5184.     
  5185.     RETURN VALUE:
  5186.     
  5187.         None
  5188.     
  5189.     
  5190.     DESCRIPTION:
  5191.     
  5192.           This function performs exactly as the  "PRINTF"  function  in  the
  5193.        standard function library, except that it  outputs  directly  to  the
  5194.        video screen using the video interface library routines.
  5195.     
  5196.           This function should be used in preference to "PRINTF" when  using
  5197.        the video function library since "PRINTF" will  not  move  the  video
  5198.        librarys cursor.
  5199.     
  5200.           NOTE: This function uses a variable number of arguments, and  must
  5201.        be declared as "register" (See "video.h").
  5202.     
  5203.           "VOPEN" MUST be called prior to using this function.
  5204.     
  5205.     
  5206.     EXAMPLES:
  5207.     
  5208.         vgotoxy(0, 0);
  5209.         vprintf("Screen %u", screen);
  5210.     VPUTC                                                             VPUTC
  5211.     
  5212.     
  5213.     
  5214.     PROTOTYPE:
  5215.     
  5216.         vputc(char chr)
  5217.     
  5218.     
  5219.     ARGUMENTS:
  5220.     
  5221.         chr     - Character to display
  5222.     
  5223.     
  5224.     RETURN VALUE:
  5225.     
  5226.         None
  5227.     
  5228.     
  5229.     DESCRIPTION:
  5230.     
  5231.           This function displays a character on  the  video  screen  at  the
  5232.        current cursor position.
  5233.     
  5234.           Characters are output in "tty" fashion, with  proper  handling  of
  5235.        control codes such as CARRIAGE-RETURN, LINE-FEED and BELL. The screen
  5236.        will scroll upwards when a NEWLINE is printed on the bottom  line  of
  5237.        the screen, or when the bottom line wraps around to the next.
  5238.     
  5239.           Although only the lower 8 bits of a passed value are used, "vputc"
  5240.        will not perform ANY output translations if any of the upper  8  bits
  5241.        are set. This provides a method of displaying  the  video  characters
  5242.        represented by control codes such as NEWLINE, and BACKSPACE.
  5243.     
  5244.           The external "char" variable "V_ATTR" may be used to set the video
  5245.        attribute used by "VPUTC" to display the  character.  This  value  is
  5246.        written to the attribute location associated with  the  character  on
  5247.        the video display hardware. Its effect  is  dependant  on  the  video
  5248.        adapter in use. The "video.h" header file contains definitions of the
  5249.        attribute bits for use on "standard" monochrome and color displays.
  5250.     
  5251.     
  5252.           "VOPEN" MUST be called prior to using this function.
  5253.     
  5254.     
  5255.     EXAMPLES:
  5256.     
  5257.         vputc(0x0A);            /* Line-feed, advance cursor */
  5258.         vputc(0x0A | 0xff00);   /* Display 0x0A character code */
  5259.     VPUTF                                                             VPUTF
  5260.     
  5261.     
  5262.     
  5263.     PROTOTYPE:
  5264.     
  5265.         vputf(char *string, int width)
  5266.     
  5267.     
  5268.     ARGUMENTS:
  5269.     
  5270.         string  - Pointer to character string
  5271.         width   - Width of output field
  5272.     
  5273.     
  5274.     RETURN VALUE:
  5275.     
  5276.         None
  5277.     
  5278.     
  5279.     DESCRIPTION:
  5280.     
  5281.           The "vputf" function outputs a  character  string  to  the  IBM-PC
  5282.        video screen using the video library functions.
  5283.     
  5284.           The string is left justified in a field of the specified width. If
  5285.        the string is shorter than "width", the field is padded with  blanks.
  5286.        If the string is longer than "width", the output is truncated.
  5287.     
  5288.           "VOPEN" MUST be called prior to using this function.
  5289.     
  5290.     
  5291.     EXAMPLES:
  5292.     
  5293.         vputf(message, 10); 
  5294.     VPUTS                                                             VPUTS
  5295.     
  5296.     
  5297.     
  5298.     PROTOTYPE:
  5299.     
  5300.         vputs(char *string)
  5301.     
  5302.     
  5303.     ARGUMENTS:
  5304.     
  5305.         string  - Pointer to character string
  5306.     
  5307.     
  5308.     RETURN VALUE:
  5309.     
  5310.         None
  5311.     
  5312.     
  5313.     DESCRIPTION:
  5314.     
  5315.           The "vputs" function outputs a  character  string  to  the  IBM-PC
  5316.        video screen using the video library functions.
  5317.     
  5318.           "VOPEN" MUST be called prior to using this function.
  5319.     
  5320.     
  5321.     EXAMPLES:
  5322.     
  5323.         vputs(message);
  5324.     VTSTC                                                             VTSTC
  5325.     
  5326.     
  5327.     
  5328.     PROTOTYPE:
  5329.     
  5330.         int vtstc()
  5331.     
  5332.     
  5333.     ARGUMENTS:
  5334.     
  5335.         None
  5336.     
  5337.     
  5338.     RETURN VALUE:
  5339.     
  5340.         0       - No key pressed
  5341.         1-127   - ASCII value of key pressed
  5342.         < 0     - Special function key as defined in "video.h"
  5343.     
  5344.     
  5345.     DESCRIPTION:
  5346.     
  5347.           The "vtstc" function  tests  for  a  key  pressed  on  the  system
  5348.        console, and  returns  its  value.  A  returned  value  of  zero  (0)
  5349.        indicates that no key was found to be pressed.
  5350.     
  5351.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  5352.        keypress will be reported, even if the VTSTC function is called after
  5353.        a key is pressed and released.
  5354.     
  5355.     
  5356.     EXAMPLES:
  5357.     
  5358.         if(vtstc() == 0x1B) /* exit loop on ESCAPE key */
  5359.             break;
  5360.     VUPDATEXY                                                     VUPDATEXY
  5361.     
  5362.     
  5363.     
  5364.     PROTOTYPE:
  5365.     
  5366.         vupdatexy()
  5367.     
  5368.     
  5369.     ARGUMENTS:
  5370.     
  5371.         None
  5372.     
  5373.     
  5374.     RETURN VALUE:
  5375.     
  5376.         None
  5377.     
  5378.     
  5379.     DESCRIPTION:
  5380.     
  5381.           This function updates the real X/Y cursor position  on  the  video
  5382.        screen to reflect the "logical" position  where  the  next  character
  5383.        will be output.
  5384.     
  5385.           The MICRO-C video library  uses  a  BIOS  interrupt  (INT  10)  to
  5386.        position the cursor, which is quite slow, compared to  the  speed  of
  5387.        the library video routines. To prevent this  from  slowing  down  the
  5388.        video output, the cursor is  only  physically  re-positioned  when  a
  5389.        "vgotoxy" or a "vgetc" is executed.
  5390.     
  5391.           This allows the library routines to run at full speed,  and  still
  5392.        put the cursor in the right place when  output  stops  and  an  input
  5393.        request is made.
  5394.     
  5395.           A side effect of this is that the cursor on the  screen  will  not
  5396.        appear to move unless  you  call  "vgotoxy"  or  "vgetc".  This  only
  5397.        affects the physical cursor on the screen, MICRO-C maintains its  own
  5398.        internal cursor location which it uses  to  determine  where  on  the
  5399.        screen the next write will occur.
  5400.     
  5401.           Some applications which run in  real  time  (Such  as  a  terminal
  5402.        emulator) do not call "vgetc", but use "vtstc" to poll  the  keyboard
  5403.        on a regular basis. In this case, the "vupdatexy" routine  should  be
  5404.        called any time that the visual position of the cursor is important.
  5405.     
  5406.           "VOPEN" MUST be called prior to using this function.
  5407.     
  5408.     
  5409.     EXAMPLES:
  5410.     
  5411.         vupdatexy();        /* position the cursor *
  5412.         c = vtstc();        /* Test for a character */
  5413.     MICRO-C Library                                                  Page: 4
  5414.  
  5415.  
  5416.     
  5417.                      +------------------------------------+
  5418.                      |                                    |
  5419.                      |  ********************************  |
  5420.                      |  * The IBM-PC WINDOWING library *  |
  5421.                      |  ********************************  |
  5422.                      |                                    |
  5423.                      +------------------------------------+
  5424.     
  5425.     
  5426.     
  5427.     
  5428.     
  5429.     
  5430.     
  5431.     
  5432.     
  5433.     
  5434.        1.3 IBM-PC WINDOWING Library
  5435.     
  5436.              The MICRO-C WINDOWING LIBRARY is a set of powerful, very  fast,
  5437.           compact, text based windowing functions for use with  the  MICRO-C
  5438.           compiler, on the IBM Personal Computer. Features  of  the  library
  5439.           include multiple open windows,  overlaid  windows  with  automatic
  5440.           save/restore  of  screen  underneath,  scrolling  within  windows,
  5441.           optional window borders, menu and form entry functions, and more.
  5442.     
  5443.              The library is organized into two parts, the first is a set  of
  5444.           assembly language routines which provides the  basic  "low  level"
  5445.           functions to open/close windows, and to output data in  them.  The
  5446.           second part of the library provides a set of 'C'  functions  which
  5447.           provide "high level"  functions  such  as  menu  and  form  entry,
  5448.           formatted printing, etc.
  5449.     MICRO-C Library                                                  Page: 5
  5450.  
  5451.  
  5452.           1.3.1 Window Control Block
  5453.     
  5454.                 Whenever a new window is opened, the windowing library  sets
  5455.              up a WINDOW CONTROL  BLOCK  (WCB)  which  contains  information
  5456.              needed to access and control the window. The format of the  WCB
  5457.              is:
  5458.     
  5459.         Offset: 0   - Current video attribute *
  5460.                 1   - Window flags (High 8 bits of w_open attrs) **
  5461.                 2   - Absolute 'X' position of top left corner of
  5462.                       active region. ***
  5463.                 3   - Absolute 'Y' position of top left corner of
  5464.                       active region. ***
  5465.                 4   - Width in characters of active region ***
  5466.                 5   - Height in characters of active region ***
  5467.                 6   - Current 'X' cursor coordinate
  5468.                 7   - Current 'Y' cursor coordinate
  5469.                 8,9 - Pointer to previous window buffer
  5470.                 10  - Previous cursor ENDING line
  5471.                 11  - Previous cursor STARTING line
  5472.                 12  - Previous cursor absolute 'X' position ****
  5473.                 13  - Previous cursor absolute 'Y' position ****
  5474.                 14..- Save area for SAVE/RESTORE function
  5475.     
  5476.         *       You may dynamically alter the video attribute of data
  5477.                 written to the window by writing to this byte.
  5478.     
  5479.         **      You may dynamically alter the properties of the window by
  5480.                 setting or clearing the flag bits with these exceptions:
  5481.                 -DO NOT enable SAVE/RESTORE unless opened with it
  5482.                 (It is Ok to disable SAVE/RESTORE).
  5483.                 -DO NOT change the state of the BORDER bits.
  5484.     
  5485.         ***     For windows opened with a BORDER, this reflects the size
  5486.                 of the active region (not including the border). Otherwise,
  5487.                 this is the size of the entire window.
  5488.     
  5489.         ****    For full screen window which does not SAVE/RESTORE, you can
  5490.                 set these values to zero to home cursor on exit.
  5491.     MICRO-C Library                                                  Page: 6
  5492.  
  5493.  
  5494.           1.3.2 External Variables
  5495.     
  5496.                 In addition to  the  functions  decribed  on  the  following
  5497.              pages, the windowing library provides  the  following  external
  5498.              variables which may be accessed from within your 'C' program:
  5499.     
  5500.              1.3.2.1 W_BASE
  5501.     
  5502.                                extern int W_BASE;
  5503.     
  5504.                    This variable contains the  base  address  of  the  video
  5505.                 screen, which may be used to determine the type  of  display
  5506.                 present:
  5507.     
  5508.                         B000 = Monochrome
  5509.                         B800 = Color
  5510.     
  5511.     
  5512.              1.3.2.2 W_OPEN
  5513.     
  5514.                               extern char *W_OPEN;
  5515.     
  5516.                    This variable contains a  pointer  to  the  WCB  for  the
  5517.                 "active" window, and controls which window is manipulated by
  5518.                 certain library functions.  This  automatically  set  up  by
  5519.                 "wopen" to point to the  last  window  opened,  but  may  be
  5520.                 changed at any time with:
  5521.     
  5522.                                 W_OPEN = window;
  5523.     
  5524.                    NOTE, when the active window is closed, W_OPEN  is  reset
  5525.                 to point to the window which was active at the time that  it
  5526.                 (the active window) was opened. If  windows  are  closed  in
  5527.                 other than the reverse order  of  which  they  were  opened,
  5528.                 W_OPEN may be left pointing to a window  which  has  already
  5529.                 been closed. If this happens, YOU MUST NOT USE THE  "ACTIVE"
  5530.                 WINDOW FUNCTIONS WITHOUT RESETTING W_OPEN  TO  POINT  TO  AN
  5531.                 OPEN WINDOW. It is your (the programmer's) responsibility to
  5532.                 insure that you know what window will  be  accessed  through
  5533.                 W_OPEN at all times throughout your program.
  5534.     
  5535.           1.3.3 Window Library Functions
  5536.     
  5537.                 The following pages contain a description of  each  function
  5538.              available in the IBM-PC windowing library.
  5539.     WCLEOL                                                           WCLEOL
  5540.     W_CLEOL                                                         W_CLEOL
  5541.     
  5542.     
  5543.     
  5544.     PROTOTYPE:
  5545.     
  5546.         wcleol()
  5547.         w_cleol(char *window)
  5548.     
  5549.     
  5550.     ARGUMENTS:
  5551.     
  5552.         window  - Pointer to WCB for an open window
  5553.     
  5554.     
  5555.     RETURN VALUE:
  5556.     
  5557.         None
  5558.     
  5559.     
  5560.     DESCRIPTION:
  5561.     
  5562.           The "wcleol" function clears the active window  from  the  current
  5563.        cursor position to the end of a line.
  5564.     
  5565.           The "w_cleol" function  clears  the  specified  window  fromt  the
  5566.        current position to the end of the line.
  5567.     
  5568.     
  5569.     EXAMPLES:
  5570.     
  5571.         wputs("Input> ");       /* Display a prompt */
  5572.         wcleol();               /* Clear remainder of input line */
  5573.     WCLEOW                                                           WCLEOW
  5574.     W_CLEOW                                                         W_CLEOW
  5575.     
  5576.     
  5577.     
  5578.     PROTOTYPE:
  5579.     
  5580.         wcleow()
  5581.         w_cleow(char *window)
  5582.     
  5583.     
  5584.     ARGUMENTS:
  5585.     
  5586.         window  - Pointer to WCB for an open window
  5587.     
  5588.     
  5589.     RETURN VALUE:
  5590.     
  5591.         None
  5592.     
  5593.     
  5594.     DESCRIPTION:
  5595.     
  5596.           The "wcleow" function clears the active window  from  the  current
  5597.        position to the end of the window.
  5598.     
  5599.           The "w_cleow"  function  clears  the  specified  window  from  the
  5600.        current position to the end of the window.
  5601.     
  5602.     
  5603.     EXAMPLES:
  5604.     
  5605.         wgotoxy(0, 10);         /* position at line 11 */
  5606.         wcleos();               /* Clear lower part of screen */
  5607.     WCLOSE                                                           WCLOSE
  5608.     W_CLOSE                                                         W_CLOSE
  5609.     
  5610.     
  5611.     
  5612.     PROTOTYPE:
  5613.     
  5614.         wclose()
  5615.         w_close(char *window)
  5616.     
  5617.     
  5618.     ARGUMENTS:
  5619.     
  5620.         window  - Pointer to WCB for an open window
  5621.     
  5622.     RETURN VALUE:
  5623.     
  5624.         None
  5625.     
  5626.     
  5627.     DESCRIPTION:
  5628.     
  5629.           The "wclose" function closes the "active" window, and de-activates
  5630.        it.
  5631.     
  5632.           The  "w_close"  function  closes   the   specified   window,   and
  5633.        de-activates it.
  5634.     
  5635.           If the window being closed is the "active"  window,  the  "active"
  5636.        window will revert to the window which was "active" at the time  that
  5637.        the window being closed was opened.
  5638.     
  5639.     
  5640.     EXAMPLES:
  5641.     
  5642.         wclose();       /* Close active window */
  5643.         w_close(title); /* Close the title window */
  5644.     WCLWIN                                                           WCLWIN
  5645.     W_CLWIN                                                         W_CLWIN
  5646.     
  5647.     
  5648.     
  5649.     PROTOTYPE:
  5650.     
  5651.         wclwin()
  5652.         w_clwin(char *window)
  5653.     
  5654.     
  5655.     ARGUMENTS:
  5656.     
  5657.         window  - Pointer to WCB for an open window
  5658.     
  5659.     
  5660.     RETURN VALUE:
  5661.     
  5662.         None
  5663.     
  5664.     
  5665.     DESCRIPTION:
  5666.     
  5667.           The "wclwin" function clears the entire active window  and  resets
  5668.        the cursor position to the top left hand corner.
  5669.     
  5670.           The "w_clwin" function clears the  entire  specified  window,  and
  5671.        resets the cursor position to the top left hand corner.
  5672.     
  5673.     
  5674.     EXAMPLES:
  5675.     
  5676.         if(c = 0x1b) {          /* Escape command */
  5677.             wclwin();           /* Clear the screen */
  5678.             wputs("Exiting back to main menu");
  5679.             return; }
  5680.     WCURSOR_BLOCK                                             WCURSOR_BLOCK
  5681.     
  5682.     
  5683.     
  5684.     PROTOTYPE:
  5685.     
  5686.         wcursor_block()
  5687.     
  5688.     
  5689.     ARGUMENTS:
  5690.     
  5691.         None
  5692.     
  5693.     
  5694.     RETURN VALUE:
  5695.     
  5696.         None
  5697.     
  5698.     
  5699.     DESCRIPTION:
  5700.     
  5701.           This function enables (turns on) display of the cursor on the  IBM
  5702.        PC video display. The cursor is shown as  flashing  block,  occupying
  5703.        the entire character window.
  5704.     
  5705.     
  5706.     EXAMPLES:
  5707.     
  5708.         if(insert)              /* Test insert mode flag */
  5709.             wcursor_block();    /* Indicate inserting with block cursor */
  5710.         else
  5711.             wcursor_line();     /* Indicate overwrite with line cursor */
  5712.     WCURSOR_LINE                                               WCURSOR_LINE
  5713.     
  5714.     
  5715.     
  5716.     PROTOTYPE:
  5717.     
  5718.         wcursor_line()
  5719.     
  5720.     
  5721.     ARGUMENTS:
  5722.     
  5723.         None
  5724.     
  5725.     
  5726.     RETURN VALUE:
  5727.     
  5728.         None
  5729.     
  5730.     
  5731.     DESCRIPTION:
  5732.     
  5733.           This function enables (turns on) display of the cursor on the  IBM
  5734.        PC video display. The cursor is shown as a single flashing  line,  at
  5735.        the bottom of the character window.
  5736.     
  5737.     
  5738.     EXAMPLES:
  5739.     
  5740.         wcursor_line();     /* Re-enable the cursor */
  5741.         exit(0);            /* And terminate */
  5742.     WCURSOR_OFF                                                 WCURSOR_OFF
  5743.     
  5744.     
  5745.     
  5746.     PROTOTYPE:
  5747.     
  5748.         wcursor_off()
  5749.     
  5750.     
  5751.     ARGUMENTS:
  5752.     
  5753.         None
  5754.     
  5755.     
  5756.     RETURN VALUE:
  5757.     
  5758.         None
  5759.     
  5760.     
  5761.     DESCRIPTION:
  5762.     
  5763.           This function inhibits (turns off) display of the  cursor  on  the
  5764.        IBM PC video display. This affects the cursor  display  only,  screen
  5765.        output will continue to be displayed at the correct cursor position.
  5766.     
  5767.     
  5768.     EXAMPLES:
  5769.     
  5770.         wclscr();           /* Clear screen */
  5771.         wcursor_off();      /* Inhibit cursor */
  5772.         wmenu(10, 10, 0x6007, main_menu, &index); /* Present main menu */
  5773.     WFORM                                                             WFORM
  5774.     
  5775.     
  5776.     
  5777.     PROTOTYPE:
  5778.     
  5779.         register wform(int x, int y, int attrs, char *prompts[],
  5780.                        char *strings,  ...)
  5781.     
  5782.     
  5783.     ARGUMENTS:
  5784.     
  5785.         x       - Absolute COLUMN of upper left corner of form window
  5786.         y       - Absolute ROW    of upper left corner of form window
  5787.         attrs   - Attributes for form window (See WOPEN)
  5788.         prompts - Prompt string for form entries
  5789.         strings - Destination string to receive form data
  5790.         ...     - Additional arguments may be required
  5791.     
  5792.     
  5793.     RETURN VALUE:
  5794.     
  5795.         None
  5796.     
  5797.     
  5798.     DESCRIPTION:
  5799.     
  5800.           The "wform" function opens  a  window,  which  contains  a  "form"
  5801.        consisting of prompts and data areas. Each data area is shown  beside
  5802.        its corresponding prompt, and may be edited using the keys  supported
  5803.        by WGETS. the UP and DOWN ARROW keys may be used to move the  editing
  5804.        cursor between the various fields in the input form.*
  5805.     
  5806.           The "attrs" argument contains the open attributes (see WOPEN)  for
  5807.        the menu window, and may  be  used  to  control  the  color,  border,
  5808.        clearing, etc.
  5809.     
  5810.           The "prompts" argument is an array of pointers to  strings,  which
  5811.        define the prompts and input  fields  in  the  form.  The  first  two
  5812.        characters of each string define the 'X' and 'Y'  coordinates  within
  5813.        the window of the prompt string. The  third  character  contains  the
  5814.        length of the destination string, and the  remainder  of  the  string
  5815.        contains the text prompt. The destination string is positioned in the
  5816.        window directly following the prompt string.  This  list  of  prompts
  5817.        must end with a NULL (0) element.
  5818.     
  5819.           The first (0) element of "prompts" does not actually point  to  an
  5820.        input definition, but contains the X and Y sizes for the window to be
  5821.        opened (High byte = X, Low byte = Y).
  5822.     
  5823.           Following the "prompts" argument, there must  be  one  destination
  5824.        "string" argument for each prompt defined. The strings must  be  long
  5825.        enough to contain the number of characters  specified  in  the  third
  5826.        byte of the coresponding "prompt" string.
  5827.           Only the lower seven bits of the field length are used  (length  =
  5828.        1-127), the high bit indicates that the field is to  contain  numbers
  5829.        only. In this case, the corresponding argument is NOT a pointer to  a
  5830.        string, but must be a pointer to an "int" variable.
  5831.     
  5832.           The form is exited by pressing the ESCAPE key.
  5833.     
  5834.     
  5835.     
  5836.     EXAMPLES:
  5837.     
  5838.         /* Sample input form */
  5839.             char *form[] = {
  5840.                 50<<8|6,        /* Place in 50 by 6 window */
  5841.                 "\x01\x00\x20Software  :",
  5842.                 "\x01\x01\x20Author    :",
  5843.                 "\x01\x02\x20Directory :",
  5844.                 "\x01\x03\x20Filename  :",
  5845.                 0 };
  5846.     
  5847.         /* Data areas for input form */
  5848.             char software[0x21] = "MICRO-C",
  5849.                 author[0x21]    = "Dave Dunfield",
  5850.                 direct[0x21]    = "C:\\MC",
  5851.                 filename[0x21]  = "MC*.*";
  5852.     
  5853.         /* Simple main program to display the form */
  5854.         main()
  5855.         {
  5856.             wform(15, 9, 0xE007, form, software, author, direct, filename);
  5857.         }
  5858.     WGETC                                                             WGETC
  5859.     W_GETC                                                           W_GETC
  5860.     
  5861.     
  5862.     
  5863.     PROTOTYPE:
  5864.     
  5865.         int wgetc()
  5866.         int w_getc(char *window)
  5867.     
  5868.     
  5869.     ARGUMENTS:
  5870.     
  5871.         window  - Pointer to WCB for an open window
  5872.     
  5873.     
  5874.     RETURN VALUE:
  5875.     
  5876.         0-127   - ASCII value of key pressed
  5877.         < 0     - Special function key as defined in "video.h"
  5878.     
  5879.     
  5880.     DESCRIPTION:
  5881.     
  5882.           The "wgetc" function waits until a key is pressed  on  the  system
  5883.        console, and returns its value. The cursor is updated to be placed at
  5884.        the current cursor position in the active window.
  5885.     
  5886.           The "w_getc" function waits until a key is pressed on  the  system
  5887.        console, and returns its value. The cursor is updated to be placed at
  5888.        the current cursor position in the specified window.
  5889.     
  5890.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  5891.        keypress will be reported, even if the WGETC or  W_GETC  function  is
  5892.        called after a key is pressed and released.
  5893.     
  5894.     
  5895.     EXAMPLES:
  5896.     
  5897.         switch(wgetc()) {       /* Handle input keys
  5898.                 . . .
  5899.         }
  5900.     WGETS                                                             WGETS
  5901.     
  5902.     
  5903.     
  5904.     PROTOTYPE:
  5905.     
  5906.         int wgets(int x, int y, char *string, int length)
  5907.     
  5908.     
  5909.     ARGUMENTS:
  5910.     
  5911.         x       - COLUMN position for input
  5912.         y       - ROW    position for input
  5913.         string  - Destination string
  5914.         length  - Length of string (High bit set = Numbers only)
  5915.     
  5916.     
  5917.     RETURN VALUE:
  5918.     
  5919.         Character causing exit
  5920.     
  5921.     
  5922.     DESCRIPTION:
  5923.     
  5924.           The "wgets" function positions the cursor at the specified X and Y
  5925.        coordinates, and displays the contents of "string"  (in  a  field  of
  5926.        "length" characters), and waits for input, which may be used to  edit
  5927.        the string.
  5928.     
  5929.           Any normal ASCII characters which are input will be  entered  into
  5930.        the string, The following function keys are recognized:
  5931.     
  5932.             LEFT ARROW          - Position cursor one space to the left
  5933.             RIGHT ARROW         - Position cursor one space to the right
  5934.             BACKSPACE           - Backup cursor & delete previous character
  5935.             DELETE              - Delete character under cursor
  5936.             INSERT              - Toggle between INSERT/OVERWRITE
  5937.             HOME                - Position cursor at start of string
  5938.             END                 - Position cursor at end of scring
  5939.             PAGE UP             - Clear entire field
  5940.             PAGE DOWN           - Clear from cursor to end of field
  5941.     
  5942.           Any other special function keys will cause "wgets"  to  terminate,
  5943.        and return the value of the offending key. (See  "window.h"  for  key
  5944.        definitions).
  5945.     
  5946.           When INSERT mode is enabled, all entered  text  will  be  inserted
  5947.        into the string, with the remainder of the  string  shifting  to  the
  5948.        right. This mode is indicated by a flashing BLOCK cursor.
  5949.     
  5950.           When OVERWRITE mode is enabled, all entered  text  will  overwrite
  5951.        the existing string. This  mode  is  indicated  by  a  flashing  LINE
  5952.        cursor.
  5953.     
  5954.     
  5955.     EXAMPLES:
  5956.     
  5957.         wgets(2, 5, name, 25);
  5958.     WGOTOXY                                                         WGOTOXY
  5959.     W_GOTOXY                                                       W_GOTOXY
  5960.     
  5961.     
  5962.     
  5963.     PROTOTYPE:
  5964.     
  5965.         wgotoxy(int x, int y)
  5966.         w_gotoxy(int x, int y, char *window)
  5967.     
  5968.     
  5969.     ARGUMENTS:
  5970.     
  5971.         x       - New COLUMN
  5972.         y       - New ROW
  5973.         window  - Pointer to WCB for an open window
  5974.     
  5975.     
  5976.     RETURN VALUE:
  5977.     
  5978.         None
  5979.     
  5980.     
  5981.     DESCRIPTION:
  5982.     
  5983.           The "wgotoxy" function positions  the  cursor  within  the  active
  5984.        window. Any further display output to that window will occur  at  the
  5985.        new ROW and COLUMN positions.
  5986.     
  5987.           The "w_gotoxy" function positions the cursor within the  specified
  5988.        window. Any further display output to that window will occur  at  the
  5989.        new ROW and COLUMN positions.
  5990.     
  5991.     
  5992.     EXAMPLES:
  5993.     
  5994.         for(i=0; i<10; ++i) {   /* Draw a diagonal line of 'X's */
  5995.             wgotoxy(i, i);
  5996.             wputc('X'); }
  5997.     WMENU                                                             WMENU
  5998.     
  5999.     
  6000.     
  6001.     PROTOTYPE:
  6002.     
  6003.         wmenu(int x, int y, int attrs, char *names[], int &index)
  6004.     
  6005.     
  6006.     ARGUMENTS:
  6007.     
  6008.         x       - Absolute COLUMN of top left corner of menu window
  6009.         y       - Absolute ROW    of top left corner of menu window
  6010.         attrs   - Attributes for menu window (see WOPEN)
  6011.         names   - Array to menu selection text (last entry = 0)
  6012.         index   - Address of message selection index variable
  6013.     
  6014.     
  6015.     RETURN VALUE:
  6016.     
  6017.         0   - Selection was made and ENTER pressed.
  6018.         !0  - Menu was aborted via ESCAPE key.
  6019.     
  6020.     
  6021.     DESCRIPTION:
  6022.     
  6023.           The "wmenu" function opens a window  containing  a  list  of  menu
  6024.        items at the specified ROW and COLUMN address. The user may  use  the
  6025.        UP, DOWN, HOME and END keys to select an entry by moving the  INVERSE
  6026.        VIDEO selection cursor. Pressing an alpha-numeric key  will  position
  6027.        the  selection  bar  to  the  first  entry  which  begins  with  that
  6028.        character.
  6029.     
  6030.           When the desired selection is under the cursor, the  selection  is
  6031.        made by pressing the ENTER key.
  6032.     
  6033.           At any time the menu selection may be  canceled  by  pressing  the
  6034.        ESCAPE key.
  6035.     
  6036.           The "attrs" argument contains the open attributes (see WOPEN)  for
  6037.        the menu window, and may  be  used  to  control  the  color,  border,
  6038.        clearing, etc.
  6039.     
  6040.           The "names" argument must be a pointer to an  array  of  character
  6041.        strings which are the selections to display. This array MUST end with
  6042.        a NULL (0) element to indicate the end of the list.
  6043.     
  6044.           The "index" argument is the address of  an  "int"  variable  which
  6045.        contains the position of the selection cursor. It controls where  the
  6046.        selection cursor will appear when the function is first invoked (0  =
  6047.        first entry), and also is assigned  the  position  of  the  selection
  6048.        cursor when the selection is made.
  6049.     
  6050.           Once a selection is made, the first character  of  that  selection
  6051.        will be hilighted in reverse video.
  6052.     
  6053.     
  6054.     
  6055.     
  6056.     EXAMPLES:
  6057.     
  6058.         char *names[] = { "One", "Two", "Three", "Four", "Five", 0 };
  6059.             . . .
  6060.         index = 0;
  6061.         if(wmenu(10, 10, 0xE007, names, &index))
  6062.             return;         /* Aborted, exit to higher level */
  6063.         switch(index) {     /* Handle selection */
  6064.             . . .
  6065.         }
  6066.     WOPEN                                                             WOPEN
  6067.     
  6068.     
  6069.     
  6070.     PROTOTYPE:
  6071.     
  6072.         char *wopen(int x, int y, int width, int height, int attrs)
  6073.     
  6074.     
  6075.     ARGUMENTS:
  6076.     
  6077.         x       - Absolute COLUMN of top left corner of window
  6078.         y       - Absolute ROW    of top left corner of window
  6079.         width   - The width of the window in characters
  6080.         height  - The height of the window in characters
  6081.         attrs   - The window attributes, BIT definitions:
  6082.                     15 - Enable SAVE/RESTORE screen under window
  6083.                 *   14 - Enable SINGLE line BORDER
  6084.                 *   13 - Enable DOUBLE line BORDER
  6085.                     12 - Enable CLEAR on OPEN
  6086.                 **  11 - Enable CLEAR on CLOSE
  6087.                 *** 10 - Disable NEWLINE (LF only)
  6088.                      9 - Enable SCROLLING in window
  6089.                      8 - Enable LINE WRAP in window
  6090.                    7-0 - Video attributes for window
  6091.     
  6092.             *   When BORDER is selected, window will include an enclosing
  6093.                 BOX. In this case, the effective height and width of the
  6094.                 active region (where text data can be written) will be
  6095.                 reduced by 2.
  6096.     
  6097.             **  Has no visual effect when SAVE/RESTORE is enabled.
  6098.     
  6099.             *** If this BIT is set, CTRL-J will behave as LINEFEED only,
  6100.                 and will not return the cursor to the left margin.
  6101.     
  6102.     RETURN VALUE:
  6103.     
  6104.         A pointer to the WCB for the newly opened window
  6105.         0 if the window could not be opened
  6106.     
  6107.     
  6108.     DESCRIPTION:
  6109.     
  6110.           The "wopen" function creates a new window on the PC video  screen.
  6111.        This newly created window is also made the "active" window, which  is
  6112.        automatically accessed by many of the windowing functions.
  6113.     
  6114.           If "wopen" is unable to allocate  enough  memory  for  the  window
  6115.        control block (WCB), it will fail and return a value of zero (0).
  6116.     
  6117.     
  6118.     EXAMPLES:
  6119.     
  6120.         /* Create a title window at top of screen */
  6121.         titlewin = wopen(0, 0, 80, 3, 0x6047);
  6122.     WPRINTF                                                         WPRINTF
  6123.     W_PRINTF                                                       W_PRINTF
  6124.     
  6125.     
  6126.     
  6127.     PROTOTYPE:
  6128.     
  6129.         register wprintf(char *format, arg, ...)
  6130.         register w_printf(char *window, char *format, arg, ...)
  6131.     
  6132.     
  6133.     ARGUMENTS:
  6134.     
  6135.         window  - Pointer to WCB for an open window
  6136.         format  - Pointer to format string
  6137.         arg     - Argument as determined by format string
  6138.         ...     - Additional arguments may be required
  6139.     
  6140.     
  6141.     RETURN VALUE:
  6142.     
  6143.         None
  6144.     
  6145.     
  6146.     DESCRIPTION:
  6147.     
  6148.           The "wprintf" function performs exactly as the  "PRINTF"  function
  6149.        in the standard function library, except that it outputs directly  to
  6150.        the active window using the low level windowing library functions.
  6151.     
  6152.           The "w_printf" function behaves similar to "wprintf", except  that
  6153.        the window to receive the output is specified as the first parameter.
  6154.     
  6155.           These functions should be used  in  preference  to  "PRINTF"  when
  6156.        using the windowing function library since "PRINTF" will not move the
  6157.        windowing librarys cursor, will not use the attributes from the  WCB,
  6158.        and will not respect the boundarys of the window.
  6159.     
  6160.           NOTE: This function uses a variable number of arguments, and  must
  6161.        be declared as "register" (See "window.h").
  6162.     
  6163.     
  6164.     EXAMPLES:
  6165.     
  6166.         wgotoxy(0, 0);
  6167.         wprintf("Window %u", screen);
  6168.     WPUTC                                                             WPUTC
  6169.     W_PUTC                                                           W_PUTC
  6170.     
  6171.     
  6172.     
  6173.     PROTOTYPE:
  6174.     
  6175.         wputc(int c)
  6176.         wputc(int c, char *window)
  6177.     
  6178.     
  6179.     ARGUMENTS:
  6180.     
  6181.         c       - Character to be written to window
  6182.     
  6183.     
  6184.     RETURN VALUE:
  6185.     
  6186.         None
  6187.     
  6188.     
  6189.     DESCRIPTION:
  6190.     
  6191.           This "wputc" function displays a character in the active window at
  6192.        the current cursor position.
  6193.     
  6194.           The "w_putc" functino displays a character in the specified window
  6195.        at the current cursor position.
  6196.     
  6197.           Characters are output in "tty" fashion, with  proper  handling  of
  6198.        control codes such as CARRIAGE-RETURN, LINE-FEED and BELL. The screen
  6199.        will scroll upwards when a NEWLINE is printed on the bottom  line  of
  6200.        the screen, or  when  the  bottom  line  wraps  around  to  the  next
  6201.        (Assuming those options are enabled in the window).
  6202.     
  6203.           Although only the lower 8 bits of a passed value are used, "vputc"
  6204.        will not perform ANY output translations if any of the upper  8  bits
  6205.        are set. This provides a method of displaying  the  video  characters
  6206.        represented by control codes such as NEWLINE, and BACKSPACE.
  6207.     
  6208.           The first byte of the window control block (WCB)  for  the  window
  6209.        contains the attributes which will be used to display the  character.
  6210.        This value is written to the attribute location associated  with  the
  6211.        character on the video display hardware. Its effect is  dependant  on
  6212.        the video  adapter  in  use.  The  "window.h"  header  file  contains
  6213.        definitions of the attribute bits for use  on  "standard"  monochrome
  6214.        and color displays.
  6215.     
  6216.     
  6217.     EXAMPLES:
  6218.     
  6219.         w_putc(0x0A, window1);      /* Line-feed, advance cursor */
  6220.         wputc(0x0A | 0xff00);       /* Display 0x0A character code */
  6221.     WPUTF                                                             WPUTF
  6222.     
  6223.     
  6224.     
  6225.     PROTOTYPE:
  6226.     
  6227.         wputf(char *string, int width)
  6228.     
  6229.     
  6230.     ARGUMENTS:
  6231.     
  6232.         string  - Pointer to character string
  6233.         width   - Width of output field
  6234.     
  6235.     
  6236.     RETURN VALUE:
  6237.     
  6238.         None
  6239.     
  6240.     
  6241.     DESCRIPTION:
  6242.     
  6243.           The "wputf" function outputs a  character  string  to  the  active
  6244.        window screen using the video library functions.
  6245.     
  6246.           The string is left justified in a field of the specified width. If
  6247.        the string is shorter than "width", the field is padded with  blanks.
  6248.        If the string is longer than "width", the output is truncated.
  6249.     
  6250.     
  6251.     EXAMPLES:
  6252.     
  6253.         wputf(message, 10); 
  6254.     WPUTS                                                             WPUTS
  6255.     W_PUTS                                                           W_PUTS
  6256.     
  6257.     
  6258.     
  6259.     PROTOTYPE:
  6260.     
  6261.         wputs(char *string)
  6262.         w_puts(char *string, char *window)
  6263.     
  6264.     
  6265.     ARGUMENTS:
  6266.     
  6267.         string  - Pointer to character string
  6268.         window  - Pointer to WCB for an open window
  6269.     
  6270.     
  6271.     RETURN VALUE:
  6272.     
  6273.         None
  6274.     
  6275.     
  6276.     DESCRIPTION:
  6277.     
  6278.           The "wputs" function outputs a  character  string  to  the  active
  6279.        window.
  6280.     
  6281.           The "w_puts" function output a character string to  the  specified
  6282.        window.
  6283.     
  6284.     
  6285.     EXAMPLES:
  6286.     
  6287.         wputs(message);
  6288.         w_puts(message, window1);
  6289.     WTSTC                                                             WTSTC
  6290.     W_TSTC                                                           W_TSTC
  6291.     
  6292.     
  6293.     
  6294.     PROTOTYPE:
  6295.     
  6296.         int wtstc()
  6297.         int w_tstc(char *window)
  6298.     
  6299.     
  6300.     ARGUMENTS:
  6301.     
  6302.         window  - Pointer to WCB for an open window
  6303.     
  6304.     
  6305.     RETURN VALUE:
  6306.     
  6307.         0       - No key pressed
  6308.         1-127   - ASCII value of key pressed
  6309.         < 0     - Special function key as defined in "video.h"
  6310.     
  6311.     
  6312.     DESCRIPTION:
  6313.     
  6314.           The "wtstc" function  tests  for  a  key  pressed  on  the  system
  6315.        console, and returns its value. If a character is found,  the  cursor
  6316.        is updated in the active window.
  6317.     
  6318.           The "w_tstc" function tests  for  a  key  pressed  on  the  system
  6319.        console, and returns its value. If a character is found,  the  cursor
  6320.        is updated in the specified window.
  6321.     
  6322.           A returned value of zero (0) indicates that no key was found to be
  6323.        pressed.
  6324.     
  6325.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  6326.        keypress will be reported, even if the WTSTC or  W_TSTC  function  is
  6327.        called after a key is pressed and released.
  6328.     
  6329.     
  6330.     EXAMPLES:
  6331.     
  6332.         if(wtstc() == 0x1B) /* exit loop on ESCAPE key */
  6333.             break;
  6334.     WUPDATEXY                                                     WUPDATEXY
  6335.     W_UPDATEXY                                                   W_UPDATEXY
  6336.     
  6337.     
  6338.     
  6339.     PROTOTYPE:
  6340.     
  6341.         wupdatexy()
  6342.         w_updatexy(char *window)
  6343.     
  6344.     
  6345.     ARGUMENTS:
  6346.     
  6347.         window  - Pointer to WCB for an open window
  6348.     
  6349.     
  6350.     RETURN VALUE:
  6351.     
  6352.         None
  6353.     
  6354.     
  6355.     DESCRIPTION:
  6356.     
  6357.           The "wupdatexy" function updates the real X/Y cursor  position  on
  6358.        the video screen to reflect the "logical"  position  where  the  next
  6359.        character will be output in the active window.
  6360.     
  6361.           The "w_updatexy" function updates the real X/Y cursor position  on
  6362.        the video screen to reflect the "logical"  position  where  the  next
  6363.        character will be output in the specified window.
  6364.     
  6365.           The MICRO-C Windowing library uses a BIOS interrupt  (INT  10)  to
  6366.        position the cursor, which is quite slow, compared to  the  speed  of
  6367.        the library video routines. To prevent this  from  slowing  down  the
  6368.        video output, the cursor is  only  physically  re-positioned  when  a
  6369.        "wgotoxy" or a "wgetc" is executed.
  6370.     
  6371.           This allows the library routines to run at full speed,  and  still
  6372.        put the cursor in the right place when  output  stops  and  an  input
  6373.        request is made.
  6374.     
  6375.           A side effect of this is that the cursor on the  screen  will  not
  6376.        appear to move unless  you  call  "wgotoxy"  or  "wgetc".  This  only
  6377.        affects the physical cursor on the screen, MICRO-C maintains its  own
  6378.        internal cursor location which it uses  to  determine  where  on  the
  6379.        screen the next write will occur.
  6380.     
  6381.           Some applications which run in  real  time  (Such  as  a  terminal
  6382.        emulator) do not call "wgetc", but use "wtstc" to poll  the  keyboard
  6383.        on a regular basis. In this case, the "wupdatexy" routine  should  be
  6384.        called any time that the visual position of the cursor is important.
  6385.     
  6386.     
  6387.     EXAMPLES:
  6388.     
  6389.         wupdatexy();        /* position the cursor *
  6390.         c = wtstc();        /* Test for a character */
  6391.  
  6392.  
  6393.  
  6394.                                 MICRO-C Library
  6395.  
  6396.                                TABLE OF CONTENTS
  6397.  
  6398.  
  6399.                                                                          Page
  6400.  
  6401.      1. THE MICRO-C LIBRARIES                                               1
  6402.  
  6403.         1.1 STANDARD Library                                                2
  6404.         1.2 IBM-PC/MS-DOS Library                                           3
  6405.         1.3 IBM-PC WINDOWING Library                                        4
  6406.